5 Improvements to OpenAPI Operation Documentation

After conducting API design and documentation reviews for over a decade, there are common mistakes that most developers make when composing their reference documentation using the OpenAPI Specification. Let’s look at five operation-specific improvements that you can make to deliver on a great developer experience while reducing the support costs of your API.

1. Expand Your Operation Descriptions:

Often, API documentation is left to the end of the schedule, resulting in a rushed set of reference documentation. The result are terse operation details that state the obvious and leave out the specifics of your well-designed and implemented API operation.

Example of an Incomplete Operation Documentation

For example, an operation might be described simply as GET /users with no further explanation, leaving users to guess what the endpoint does.

Example Mistake:

paths:
  /users:
    get:
      summary: "Get users"
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            default: 10
      responses:
        200:
          description: "OK"

Improved Version:

Detailed and clear descriptions enhance understanding and usability. The improved version should thoroughly explain the operation, including its purpose, parameters, and response types.

Improved Example:

paths:
  /users:
    get:
      summary: "Retrieves a paginated list of users"
      description: >
        This operation returns a paginated list of users registered in the system,
        including their usernames and contact information. Use query parameters
        for filtering and sorting the result set.
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            default: 10
          description: "Limit the number of users returned. Defaults to 10 if not specified"
      responses:
        200:
          description: "A paginated list of users with detailed information"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'

2. Add Examples to Your API Operations and Schema

Ever since OpenAPI v3, examples have been built-in to the specification. OpenAPI examples are used to replace the default values generated by documentation rendering frameworks, such as SwaggerUI or Bump.sh. They offer the API provider the ability to customize the examples generated by these documentation frameworks to make it easier to understand your API operation.

In addition to better understanding, they also allow teams to document a common use case across operations. The example response of one operation can be used as examples for the input of another, further improving understanding and reducing the time it takes for developers to successfully integrate your API.

Example of missing example values

Below is an example of API reference documentation that lacks example values.

Example Mistake:

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string

Improved Version with Example Values:

Adding examples helps users understand how to interact with the API more effectively. It illustrates what to expect in requests and responses.

Improved Example:

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          example: "a3a39bcb1f94049d"
        name:
          type: string
          example: "John Doe"

By leveraging values that are synthetic but perhaps more realistic, it helps the developer to better understand what the operation may require in a request or return in a response. Additionally, maintaining consistency between examples help to improve the understanding of how the API operation works.

3. Add Common Response Code Documentation

With limited time available, API operations may only include documentation for common response codes like 200 OK and 500 Internal Server Error, neglecting other important status codes. Status codes such as 201 Created, 202 Accepted, 400 Bad Request, 401 Unauthorized, and 404 Not Found are also useful to document.

Some API providers have opted to use RFC 9457 Problem Details format (formally RFC 7807) to provide a consistent error message format. By documenting common response codes, not only does it inform the consumer of what to expect when errors occur, it also guides them on the error format of the response.

Of course, any HTTP client must be prepared to handle any response code - even those not documented in the OpenAPI documentation for your API. However, the more response codes you explicitly document, the more likely they will catch and handle those errors within the client code.

Example Operation with Limited Response Codes

Example Mistake:

responses:
  200:
    description: "Success"
  500:
    description: "Server Error"

Improved Version with Common Error Response Codes

Improved Example:

responses:
  200:
    description: "Success"
    …
  400:
    description: "Bad Request - Invalid parameters"
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ProblemDetails'
  401:
    description: "Unauthorized - Authentication failed"
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ProblemDetails'
  404:
    description: "Not Found - Resource doesn’t exist"
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ProblemDetails'
  500:
    description: "Internal Server Error - System encountered an unexpected error"
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ProblemDetails'

4. Organize and Tag Your API Operations

While most developers will never look at the underlying YAML for your reference documentation, most documentation rendering frameworks will render operations in the order that they are captured. This means that related operations that are scattered across your OpenAPI document will make it more difficult for the developer to understand how to use your API and what capabilities it offers.

At a minimum, group your operations so that they render together and in a thoughtful manner that helps with understanding. You may also wish to use tags to group related operations together. Tags are simply a grouping mechanism that helps documentation frameworks organize the display of your API operations.

Example of Disorganized API Operation Documentation

Documentation that lacks structure, such as grouping related endpoints or models, can be challenging to navigate and understand.

Example Mistake:

paths:
  /users:
    get: ...
  /orders:
    get: ...
  /users/{id}:
    get: ...

Well-Organized and Tagged API Operations

Improved Example:

tags:
  - name: User Management
    description: Manages the registered users in the system
  - name: Order Management
    description: Supports order creation and status lookup
paths:
  /users:
    get: ...
      tags:
        - User Management

  /users/{id}:
    get: ...
      tags:
        - User Management
  /orders:
    get: ...
      tags:
        - Order Management

Refer to our guide, "Using OpenAPI and AsyncAPI Tags to Better Organize API Endpoints" for further details on using tagging in your OpenAPI description.

5. Improve Consistency in Operation Naming Conventions

Inconsistent naming conventions for operations, parameters, and schema properties can lead to confusion and errors in API integration. Since making changes to these conventions can break your consumers, it is important to take a fresh look at your API operations, parameters, and schema definitions before releasing your API.

To further improve your API design efforts, involve your technical writers earlier in the API design process. This will provide insights regarding improvements that could be made to improve the developer experience. By shifting your technical writer involvement earlier in the API lifecycle, you also reduce the cost of change due to late feedback.

An Example of Inconsistent or Unclear Naming

Below is an example of API operations that don’t follow a consistent naming convention, resulting in an increased likelihood of mistakes when integrating your API.

Example Mistake:

paths:
  /calcSalesTax:
    post: ...
  /vatCalculation:
    post: ...
components:
  schemas:
    CalculationResponse:
      type: object
      properties:
        amount:
          type: number
          format: double
        …

Improved Version:

Using a consistent, predictable naming convention improves readability and usability of the API documentation.

Improved Example:

paths:
  /calculateSalesTax:
    post: ...
  /calculateVatTax:
    post: ...
components:
  schemas:
    CalculatedTax:
      type: object
      properties:
        amount:
          type: number
          format: double
        currency:
          type: String
        …

Bonus: Applying OpenAPI Specification Overlays

For teams that are generating OpenAPI Specification documents directly from their code using annotations, technical writers can further benefit from the use of OpenAPI overlays. Refer to our article that details using overlays to improve your tech writing workflow.

Final Thoughts on Improving Your API Documentation

Creating a high-quality API document requires attention to detail, thoroughness, and a focus on the user's experience. Take the additional time to review your documentation, look for areas to improve, and identify design flaws early so that they can be corrected with minimal impact to developers. Doing so will produce clear, comprehensive, and usable API documentation that results in a better developer experience.