Swagger Error Response Documentation Examples

Introduction

Swagger, now known as OpenAPI Specification, is a powerful tool for defining APIs. It allows developers to visualize and document their API endpoints effectively, making it easier for both frontend and backend teams to understand how to interact with the API. One crucial aspect of API documentation is error response handling. A well-documented error response can significantly improve the user experience by providing clear insights into what went wrong. Here are three diverse examples of using Swagger to document error responses.

Example 1: Documenting a 404 Not Found Error

When building a RESTful API, it’s common to encounter scenarios where a requested resource is not found. Documenting this error response helps clients understand what went wrong and how to handle it.

In this case, let’s assume we have an API endpoint that retrieves user data by ID. If a user tries to access a non-existent user, we should return a 404 error.

paths:
  /users/{id}:
    get:
      summary: Retrieve user by ID
      parameters:

        - name: id
          in: path
          required: true
          description: The ID of the user to retrieve
          schema:
            type: string
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
        '404':
          description: User not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: 'User not found'
                  code:
                    type: integer
                    example: 404

This example clearly specifies the 404 error response, providing an error message and code, which helps developers handle this case appropriately in their applications.

Example 2: Handling Authentication Errors

Another common scenario in APIs is authentication failures. It’s essential to document error responses for unauthorized access attempts so that clients can understand what is required to gain access.

Consider an API endpoint for accessing user settings that requires authentication. If a client tries to access this endpoint without valid credentials, we should return a 401 Unauthorized error.

paths:
  /user/settings:
    get:
      summary: Retrieve user settings
      security:

        - api_key: []
      responses:
        '200':
          description: Settings retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  theme:
                    type: string
                  notifications:
                    type: boolean
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: 'Unauthorized access'
                  code:
                    type: integer
                    example: 401

This documentation provides clear information about the authentication error, allowing clients to implement proper error handling and prompt users for valid credentials.

Example 3: Documenting a 500 Internal Server Error

Internal server errors can occur for various reasons, and documenting this error response is crucial to inform clients that something went wrong on the server side. This allows them to handle such situations gracefully.

Let’s say we have an API endpoint that processes payment transactions. If an unexpected error occurs during processing, we should return a 500 Internal Server Error.

paths:
  /payments:
    post:
      summary: Process a payment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: number
                currency:
                  type: string
      responses:
        '200':
          description: Payment processed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  transactionId:
                    type: string
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: 'Internal server error'
                  code:
                    type: integer
                    example: 500

By documenting the 500 error response, clients are informed that an internal issue occurred, allowing them to implement fallback mechanisms or notify users.

Conclusion

Clear documentation of error responses is essential for any API. By using Swagger to define these responses, you provide developers with the necessary information to handle errors effectively, improving the overall usability of your API.