Ensure Common Responses Defined

Ensure that the common responses for each operation are defined in OpenAPI using the responses keyword. This is useful to cover the common or expected scenarios for those operations and to inform the consumers of the API about the possible outcomes. For example, a 404 response indicates that the requested resource was not found.

Suggest Edits

Risk Level: medium
Platform: OpenAPI
Spectral Rule ID: OPENAPI012

REMEDIATION

Define the responses field for each operation and list the appropriate response codes and descriptions for each scenario. You can use references to reuse common responses across multiple operations. For example:

  paths:
    /users/{id}:
      get:
        summary: Get user by ID
        parameters:
          - name: id
            in: path
            required: true
            schema:
              type: integer
        responses:
          '200':
            description: OK
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/User'
          '400':
            $ref: '#/components/responses/BadRequest'
          '401':
            $ref: '#/components/responses/Unauthorized'
          '403':
            $ref: '#/components/responses/Forbidden'
          '404':
            $ref: '#/components/responses/NotFound'
          '429':
            $ref: '#/components/responses/TooManyRequests'
          '500':
            $ref: '#/components/responses/InternalServerError'

The above example defines a get operation that returns a user object by its ID. It also defines the common responses for this operation, such as 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 429 Too Many Requests, and 500 Internal Server Error. These responses are defined in the global components.responses section and referenced via $ref.

Case	Statuses
Put operation	500, 429, 400, 415, 404, 401, 403
Post operation	500, 429, 400, 415, 401, 403
Patch operation	500, 429, 400, 415, 404, 401, 403
Get operation	500, 429, 400, 404, 401, 403
Head operation	500
Delete operation	500, 429, 400, 404, 401, 403
Options operation	200

openapi: '3.0.0'
info:
  version: 1.0.0
  title: Sample API
paths:
  /users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
+       '400':
+         $ref: '#/components/responses/BadRequest'
+       '401':
+         $ref: '#/components/responses/Unauthorized'
+       '403':
+         $ref: '#/components/responses/Forbidden'
+       '404':
+         $ref: '#/components/responses/NotFound'
+       '429':
+         $ref: '#/components/responses/TooManyRequests'
+       '500':
+         $ref: '#/components/responses/InternalServerError'
  /products/{id}:
    put:
      summary: Update product by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Product'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
+       '400':
+         $ref: '#/components/responses/BadRequest'
+       '401':
+         $ref: '#/components/responses/Unauthorized'
+       '403':
+         $ref: '#/components/responses/Forbidden'
+       '404':
+         $ref: '#/components/responses/NotFound'
+       '415':
+         $ref: '#/components/responses/UnsupportedMediaType'
+       '429':
+         $ref: '#/components/responses/TooManyRequests'
+       '500':
+         $ref: '#/components/responses/InternalServerError'
  /options/{id}:
    options:
      summary: Get options for resource by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  methods:
                    type: array
                    items:
                      type: string
+       '400':
+         $ref: '#/components/responses/BadRequest'
+       '401':
+         $ref: '#/components/responses/Unauthorized'
+       '403':
+         $ref: '#/components/responses/Forbidden'
+       '404':
+         $ref: '#/components/responses/NotFound'
+       '429':
+         $ref: '#/components/responses/TooManyRequests'
+       '500':
+         $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
          format: email
    Product:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        price:
          type: number
          format: float
  responses:
    BadRequest:
      description: Bad request. The request parameters are invalid.
    Unauthorized:
      description: Unauthorized. The request requires authentication.
    Forbidden:
      description: Forbidden. The request is not authorized to access the resource.
    NotFound:
      description: Not found. The requested resource was not found.
    UnsupportedMediaType:
      description: Unsupported media type. The request body has an unsupported format.
    TooManyRequests:
      description: Too many requests. The request was rejected due to rate limiting.
    InternalServerError:
      description: Internal server error. The server encountered an unexpected condition that prevented it from fulfilling the request.

Updated over 1 year ago

REMEDIATION

Read more: