Last updated

Response Object

The response object describes a single response in the Responses Map.

It can be described in a separate file or in the components.responses section and reused as a reference object.

Excerpt from the OpenAPI 3.1 specification about the response object

Describes a single response from an API Operation, including design-time, static links to operations based on the response.

Fixed Fields
Field NameTypeDescription
descriptionstringREQUIRED. A description of the response. CommonMark syntax MAY be used for rich text representation.
headersMap[string, Header Object | Reference Object]Maps a header name to its definition. RFC7230 states header names are case insensitive. If a response header is defined with the name "Content-Type", it SHALL be ignored.
contentMap[string, Media Type Object]A map containing descriptions of potential response payloads. The key is a media type or media type range and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*
linksMap[string, Link Object | Reference Object]A map of operations links that can be followed from the response. The key of the map is a short name for the link, following the naming constraints of the names for Component Objects.

This object MAY be extended with Specification Extensions.

A response object is connected to the Responses Map which will have possible keys of:

  • default, or
  • HTTP codes (such as '200', '201', '400', and so on)
  • HTTP ranges ('1XX', '2XX', '3XX', '4XX', or '5XX')

The examples use '200' as the responses map key.

(Why? Because everything's going to be OK.)

Visuals

description

REQUIRED. A description of the response.

responses:
  '200':
    description: OK
  '201':
    description: Created
  '202':
    description: Accepted

success response description

headers

The named headers are specific to responses. These are different from request headers which are types of parameters in OpenAPI. The main differences are:

  1. name MUST NOT be specified, it is given in the corresponding headers map.
  2. in MUST NOT be specified, it is implicitly in header.
  3. All traits that are affected by the location MUST be applicable to a location of header (for example, style).

Also, a common oversight is that the Content-Type header name is ignored.

The headers map is a map of header names as the map keys, and header objects as the values.

responses:
  '200':
    description: OK
    headers:
      Pagination-Count:
        description: The count of items in the collection.
        schema:
          type: integer

pagination-count header

Learn more about the Header Object.

content

A map containing descriptions of potential response payloads. The key is a media type or media type range and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/*.

The "Accept" header field can be used by user agents to specify response media types that are acceptable.

Common media types:

  • application/json
  • application/xml
  • image/png
  • image/*
  • application/pdf
  • text/plain
  • text/html
  • text/csv
  • application/octet-stream

See a list of all registered media types.

The value in the content map is a Media Type Object.

responses:
  200:
    description: Success
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/ChessResult"

Response content chess result

Links are rarely used.

Redocly doesn't visualize the links. If you have an idea for how to visualize the links, please let us know in a GitHub issue comment.

Types

  • Response
  • MediaTypesMap
const Response: NodeType = {
  properties: {
    description: { type: 'string' },
    headers: mapOf('Header'),
    content: 'MediaTypesMap',
    links: mapOf('Link'),
  },
  required: ['description'],
};
 
Next page