Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 37 ยท Documentation Tools

Writing Great API Descriptions and Examples

Learn how to write summaries, Markdown descriptions, tags, examples and deprecation notes in OpenAPI so generated docs are clear, plus a runnable documentation coverage checker.

The best documentation tool cannot save a spec with no words in it. Every viewer, generator and mock server shows exactly what you wrote in summary, description, example and tags. This lesson covers how to write those fields so that the generated docs answer questions instead of raising them.

Summary versus description

Operations have two text fields with different jobs:

  • summary is a short label (a few words, no final period) shown in lists and navigation.
  • description is the full explanation. It supports CommonMark Markdown: lists, code, links and tables.
YAML
paths:
  /books/{bookId}:
    get:
      operationId: getBook
      summary: Get a book
      description: |
        Returns one book by its identifier.

        - Unknown identifiers return `404`.
        - Withdrawn books are still returned with `status: withdrawn`.
      tags: [Books]

Write the summary in the imperative or as a noun phrase, consistently across the spec: "List books", "Create a book", "Delete a book".

Describe everything a person must decide

Good descriptions answer the questions that a developer actually has:

Element Say this
Parameter What it filters or identifies, units, allowed range, default
Request body Which fields matter most, what is immutable
Response What the status means and what the client should do
Schema property Meaning, format, example, whether it can be null
Error responses The cause and how to fix it (401, 403, 404, 409, 422, 429)

Avoid empty descriptions such as "The id" or "Book object". Instead write "Unique identifier assigned by the server; never changes."

Examples make docs concrete

Add examples at three levels:

YAML
components:
  schemas:
    Book:
      type: object
      required: [id, title]
      properties:
        id:
          type: string
          description: Server-assigned identifier.
          examples: ["b-1024"]
        title:
          type: string
          examples: ["Dune"]

For whole bodies, use example (one) or examples (several, each named) on a media type:

YAML
responses:
  "200":
    description: The book.
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/Book"
        examples:
          available:
            summary: A book in stock
            value: {id: b-1024, title: Dune, status: available}
          withdrawn:
            summary: A withdrawn book
            value: {id: b-7, title: Old Title, status: withdrawn}

In OpenAPI 3.1 a schema uses the JSON Schema keyword examples (an array); the older single example keyword on a schema is deprecated in 3.1 but still seen. On media types and parameters both example and examples (a map) exist. Mock servers and Swagger UI use these values, so wrong examples cause real confusion.

Tags tell the story

Tags group operations. Define them at the top level with a description so viewers can show an introduction per group:

YAML
tags:
  - name: Books
    description: Browse and manage the catalog.
  - name: Orders
    description: Place and track purchases.
    externalDocs:
      description: Ordering guide
      url: https://example.com/guides/orders

An operation can carry several tags, but most viewers will show it once per tag, so use a single primary tag unless duplication is intended.

Deprecation and lifecycle

Mark outdated operations, parameters and schema properties with deprecated: true and explain the replacement in the description:

YAML
/books/search:
  get:
    deprecated: true
    summary: Search books (old)
    description: Deprecated. Use `GET /books?q=` instead. Removal planned after 2027-03-01.

Viewers draw a strike-through; generators add a deprecation annotation to the SDK method.

A documentation coverage checker

You can measure how well a spec is documented with a short script. The stand-in below counts the operations that lack a summary or description, parameters without a description, and responses without examples. Linting tools like Spectral do the same with rules, as you will see in the linting lesson.

Python Stand-in: documentation coverage report

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

You can see that the check is just a walk over the document, which is why rule engines are easy to extend with your own conventions.

A short style checklist

  • One sentence per summary, consistent mood, no trailing period.
  • Descriptions in plain language, US or UK spelling chosen once.
  • Every parameter, property and response has a description.
  • Every 2xx and common error has an example.
  • Link to guides with externalDocs instead of pasting long tutorials.
  • Mention rate limits, pagination and idempotency where they apply.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. What is the difference between summary and description?

    Summary is the one-line label in lists. Description is the longer CommonMark text.
  2. 2. How do you document that an operation will be removed?

    The flag lets viewers and SDKs warn users while the text explains the alternative and timeline.
  3. 3. Where are named response examples defined?

    A media type object can hold an examples map with named entries.

Summary

  • Summaries are short labels; descriptions are CommonMark explanations.
  • Describe parameters, properties and errors with real information, not restating the name.
  • Add examples to schemas and media types; viewers and mock servers use them.
  • Define tags with descriptions and mark outdated items with deprecated: true.
  • A small script (or Spectral) can measure documentation coverage.

Next: Linting OpenAPI with Spectral