OpenAPI Responses

The Responses Object is a map of Response Objects or References to Response Objects that define the possible responses that can be returned from executing the operation.

The keys in the map represent any known HTTP status codes that the API may return. The HTTP status codes can be defined as follows:

Numeric Status Code: Exact codes like 200, 404, or 500. HTTP status codes are defined in RFC 9110 (opens in a new tab).
Status Code Wildcards: Ranges like 2XX or 4XX (matching 200-299 or 400-499).
default: A catch-all for any other status codes not explicitly defined.

All values must be defined as explicit strings (for example,"200") to allow for compatibility between JSON and YAML.

Here’s a basic example of responses defined for an API endpoint:

paths:
  /drinks:
    get:
      operationId: listDrinks
      summary: Get a list of drinks.
      description: Get a list of drinks, if authenticated this will include stock levels and product codes otherwise it will only include public information.
      tags:
        - drinks
      parameters:
        - name: type
          in: query
          description: The type of drink to filter by. If not provided all drinks will be returned.
          required: false
          schema:
            $ref: "#/components/schemas/DrinkType"
      responses:
        "200":
          description: A list of drinks.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Drink"
        "5XX":
          description: An error occurred interacting with the API.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"

The Response Object in OpenAPI

The response object describes a single possible response from an API operation.

Field	Type	Required	Description
`description`	String	✅	A description of the response. May contain CommonMark syntax (opens in a new tab) to provide a rich description.
`headers`	Headers		A map of header objects that defines the headers that can be returned from executing the operation.
`content`	Content		A map of media type objects that defines the possible media types that can be returned from executing the operation.
`links`	Links		A map of link objects or References that define the possible links that can be returned from executing the operation.
`x-*`	Extensions		Any number of extension fields can be added to the response object that can be used by tooling and vendors.

Documenting Arrays in Responses

Here’s how to effectively document collections of items returned by an API.

Basic Array Response

For simple arrays, use the type: array with items pointing to your schema:

"200":
  description: A list of products.
  content:
    application/json:
      schema:
        type: array
        items:
          $ref: "#/components/schemas/Product"

Nested Arrays

For collections containing nested arrays, define the hierarchy clearly:

"200":
  description: Categories with their products.
  content:
    application/json:
      schema:
        type: array
        items:
          type: object
          properties:
            categoryName:
              type: string
            products:
              type: array
              items:
                $ref: "#/components/schemas/Product"

Tips for Documenting Arrays in Response Objects

Provide examples that show empty, single-item, and multi-item responses.
Consider pagination for potentially large collections (see next section).
Document sorting order in the description if there’s a default ordering.

Documenting Pagination

APIs that return large collections should implement pagination (opens in a new tab). You can document pagination using an envelope pattern with pagination metadata or cursor-based pagination.

Envelope pattern with pagination metadata

This approach wraps the result array in an object that includes pagination information as properties:

"200":
  description: A paginated list of orders.
  content:
    application/json:
      schema:
        type: object
        properties:
          data:
            type: array
            items:
              $ref: "#/components/schemas/Order"
          pagination:
            type: object
            properties:
              totalItems:
                type: integer
                example: 100
              currentPage:
                type: integer
                example: 2
              itemsPerPage:
                type: integer
                example: 10

Cursor-based pagination

For time-ordered or very large collections, cursor-based pagination is more efficient:

"200":
  description: A list of events with cursor-based pagination.
  content:
    application/json:
      schema:
        type: object
        properties:
          events:
            type: array
            items:
              $ref: "#/components/schemas/Event"
          next_cursor:
            type: string
            example: "YXVsdCBhbmQgdGhlIGZ1cmlvdXM="
          has_more:
            type: boolean
            example: true

Varying Response Schemas

An endpoint may need to return different response schemas depending on input parameters.

Using oneOf for Response Variations

"200":
  description: User data with varying detail levels
  content:
    application/json:
      schema:
        oneOf:
          - $ref: "#/components/schemas/UserBasic"
          - $ref: "#/components/schemas/UserDetailed"

Documenting the Parameter-Response Relationship

Be sure to document the parameters that affect the response structure:

parameters:
  - name: detail
    in: query
    schema:
      type: string
      enum: [basic, full]
    description: >
      Controls response detail level:
      * basic - Returns id, name, and email only
      * full - Returns all user information including preferences

responses:
  "200":
    description: User profile information
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/UserProfile"

Documenting Deeply Nested Objects

Complex APIs often return deeply nested responses. You can use schema references to keep documentation readable:

"200":
  description: Detailed analytics report
  content:
    application/json:
      schema:
        type: object
        properties:
          summary:
            $ref: "#/components/schemas/ReportSummary"
          metrics:
            $ref: "#/components/schemas/ReportMetrics"
          segments:
            type: object
            properties:
              byCountry:
                $ref: "#/components/schemas/CountrySegment"
              byDevice:
                $ref: "#/components/schemas/DeviceSegment"

Binary Responses

Many APIs need to return non-JSON responses like files, images, or other binary data. You can typically use the {mediatype}/{subtype} MIME type format (opens in a new tab) to define these responses:

File Downloads

For endpoints that return downloadable files, specify the file type and include headers for an example of the file download name:

"200":
  description: The requested PDF report
  content:
    application/pdf:
      schema:
        type: string
        format: binary
  headers:
    Content-Disposition:
      schema:
        type: string
        example: 'attachment; filename="report-2023.pdf"'
      description: Specifies the file download name

Multiple Media Types

If an endpoint supports multiple response formats, list them all in the response definition:

"200":
  description: The requested image
  content:
    image/png:
      schema:
        type: string
        format: binary
    image/jpeg:
      schema:
        type: string
        format: binary
    image/webp:
      schema:
        type: string
        format: binary

Error Response Patterns

Consistent error responses help developers understand what to expect in the event of an error or malformed request. The standard error structure looks similar to this:

"400":
  description: Bad request - invalid input
  content:
    application/json:
      schema:
        type: object
        properties:
          error:
            type: object
            properties:
              code:
                type: string
                example: "validation_error"
              message:
                type: string
                example: "Invalid email format"

Tips for Error Responses

Use descriptive error codes that clearly identify the error type.
Include helpful error messages that explain what went wrong.
Add error details for field-specific validation errors.
Include request identifiers to help with troubleshooting.
Document all possible error responses in the OpenAPI document.

Response Envelope Patterns

Response envelopes provide consistent structure across an API.

Data Wrapper Pattern

This pattern wraps the response data in a standard object, allowing you to include metadata such as request IDs or timestamps:

"200":
  description: Success response with data wrapper
  content:
    application/json:
      schema:
        type: object
        properties:
          data:
            $ref: "#/components/schemas/User"
          meta:
            type: object
            properties:
              requestId:
                type: string
              timestamp:
                type: string
                format: date-time

Hypermedia Links

REST APIs that implement HATEOAS (opens in a new tab) return both data and links that clients can use to navigate the API:

"200":
  description: User details with navigation links
  content:
    application/json:
      schema:
        type: object
        properties:
          data:
            $ref: "#/components/schemas/User"
          links:
            type: object
            properties:
              self:
                type: string
                format: uri
              followers:
                type: string
                format: uri