Describing Responses

An API specification needs to specify the responses for all API operations. Each operation must have at least one response defined, usually a successful response. A response is defined by its HTTP status code and the data returned in the response body and/or headers. Here is a minimal example:

1
paths:
2
  /ping:
3
    get:
4
      produces:
5
        - application/json
6
      responses:
7
        200:
8
          description: OK

Response Media Types

An API can respond with various media types. JSON is the most common format for data exchange, but not the only one possible. To specify the response media types, use the produces keyword on the root level or operation level. The global list can be overridden on the operation level.

1
produces:
2
  - application/json
3

4
paths:
5
  # This operation returns JSON - as defined globally above
6
  /users:
7
    get:
8
      summary: Gets a list of users.
9
      responses:
10
        200:
11
          description: OK
12
  # Here, we override the "produces" array to specify other media types
13
  /logo:
14
    get:
15
      summary: Gets the logo image.
16
      produces:
17
        - image/png
18
        - image/gif
19
        - image/jpeg
20
      responses:
21
        200:
22
          description: OK

More info: MIME Types.

HTTP Status Codes

Under responses, each response definition starts with a status code, such as 200 or 404. An operation typically returns one successful status code and one or more error statuses. Each response status requires a description. For example, you can describe the conditions for error responses. GitHub Flavored Markdown can be used for rich text representation.

1
responses:
2
  200:
3
    description: OK
4
  400:
5
    description: Bad request. User ID must be an integer and bigger than 0.
6
  401:
7
    description: Authorization information is missing or invalid.
8
  404:
9
    description: A user with the specified ID was not found.

Note that an API specification does not necessarily need to cover all possible HTTP response codes, since they may not be known in advance. However, it is expected to cover successful responses and any known errors. By “known errors” we mean, for example, a 404 Not Found response for an operation that returns a resource by ID, or a 400 Bad Request response in case of invalid operation parameters.

Response Body

The schema keyword is used to describe the response body. A schema can define:

object or array – typically used with JSON and XML APIs,
a primitive such as a number or string – used for plain text responses,
file (see below).

Schema can be defined inline in the operation:

1
responses:
2
  200:
3
    description: A User object
4
    schema:
5
      type: object
6
      properties:
7
        id:
8
          type: integer
9
          description: The user ID.
10
        username:
11
          type: string
12
          description: The user name.

or defined at the root level and referenced via $ref. This is useful if multiple responses use the same schema.

1
      responses:
2
        200:
3
          description: A User object
4
          schema:
5
            $ref: '#/definitions/User'
6
definitions:
7
  User:
8
    type: object
9
    properties:
10
      id:
11
        type: integer
12
        description: The user ID.
13
      username:
14
        type: string
15
        description: The user name.

Response That Returns a File

An API operation can return a file, such as an image or PDF. In this case, define the response schema with type: file and specify the appropriate MIME types in the produces section.

1
paths:
2
  /report:
3
    get:
4
      summary: Returns the report in the PDF format.
5
      produces:
6
        - application/pdf
7
      responses:
8
        200:
9
          description: A PDF file.
10
          schema:
11
            type: file

Empty Response Body

Some responses, such as 204 No Content, have no body. To indicate the response body is empty, do not specify a schema for the response. Swagger treats no schema as a response without a body.

1
responses:
2
  204:
3
    description: The resource was deleted successfully.

Response Headers

Responses from an API can include custom headers to provide additional information on the result of an API call. For example, a rate-limited API may provide the rate limit status via response headers as follows:

1
HTTP 1/1 200 OK
2
X-RateLimit-Limit: 100
3
X-RateLimit-Remaining: 99
4
X-RateLimit-Reset: 2016-10-12T11:00:00Z
5

6
{ ... }

You can define custom headers for each response as follows:

1
paths:
2
  /ping:
3
    get:
4
      summary: Checks if the server is alive.
5
      responses:
6
        200:
7
          description: OK
8
          headers:
9
            X-RateLimit-Limit:
10
              type: integer
11
              description: Request limit per hour.
12
            X-RateLimit-Remaining:
13
              type: integer
14
              description: The number of requests left for the time window.
15
            X-RateLimit-Reset:
16
              type: string
17
              format: date-time
18
              description: The UTC date/time at which the current rate limit window resets.

Note that, currently, there is no way in Swagger to define common response headers for different response codes or different API operations. You need to define the headers for each response individually.

Default Response

Sometimes, an operation can return multiple errors with different HTTP status codes, but all of them have the same response structure:

1
responses:
2
  200:
3
    description: Success
4
    schema:
5
      $ref: "#/definitions/User"
6
  400:
7
    description: Bad request
8
    schema:
9
      $ref: "#/definitions/Error" # <-----
10
  404:
11
    description: Not found
12
    schema:
13
      $ref: "#/definitions/Error" # <-----

You can use the default response to describe these errors collectively, not individually. “Default” means this response is used for all HTTP codes that are not covered individually for this operation.

1
responses:
2
  200:
3
    description: Success
4
    schema:
5
      $ref: "#/definitions/User"
6
  # Definition of all error statuses
7
  default:
8
    description: Unexpected error
9
    schema:
10
      $ref: "#/definitions/Error"

Reusing Responses

If multiple operations return the same response (status code and data), you can define it in the global responses section and reference that definition via $ref at the operation level. This is useful for error responses with the same status codes and response body.

1
paths:
2
  /users:
3
    get:
4
      summary: Gets a list of users.
5
      response:
6
        200:
7
          description: OK
8
          schema:
9
            $ref: "#/definitions/ArrayOfUsers"
10
        401:
11
          $ref: "#/responses/Unauthorized" # <-----
12
  /users/{id}:
13
    get:
14
      summary: Gets a user by ID.
15
      response:
16
        200:
17
          description: OK
18
          schema:
19
            $ref: "#/definitions/User"
20
        401:
21
          $ref: "#/responses/Unauthorized" # <-----
22
        404:
23
          $ref: "#/responses/NotFound" # <-----
24
# Descriptions of common responses
25
responses:
26
  NotFound:
27
    description: The specified resource was not found
28
    schema:
29
      $ref: "#/definitions/Error"
30
  Unauthorized:
31
    description: Unauthorized
32
    schema:
33
      $ref: "#/definitions/Error"
34
definitions:
35
  # Schema for error response body
36
  Error:
37
    type: object
38
    properties:
39
      code:
40
        type: string
41
      message:
42
        type: string
43
    required:
44
      - code
45
      - message

Note that responses defined at the root level are not automatically applied to all operations. These are just definitions that can be referenced and reused by multiple operations.

FAQ

Can I have different responses based on a request parameter? Such as:

1
GET /something -> {200, schema_1}
2
GET /something?foo=bar -> {200, schema_2}

No, this is not supported.

Reference

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#responsesDefinitionsObject

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#responsesObject

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#responseObject

Did not find what you were looking for? Ask the community
Found a mistake? Let us know