How to Document an API with Swagger – Step by Step

February 10, 2025 | 6 Min.

Author: dataliquid GmbH

Installation and Setup of Swagger

Swagger is a powerful open-source tool for API documentation. It is used for the structured description, visualization, and interaction with APIs. Developers benefit from clear, interactive documentation that significantly facilitates the use and maintenance of APIs. With Swagger, API specifications can be comprehensively captured and displayed, providing an accurate reflection of the current state of an API. This not only promotes traceability, but also eases collaboration between developers. Before using Swagger, it must be installed and configured according to the technology stack, with various integration options available.

Installation

Depending on the technology stack, there are different ways to integrate Swagger. The most common options are:

Swagger UI, a user interface for visualizing and interacting with API documentation. It can be integrated via a CDN or locally, providing an interactive view of the API.
Swagger Editor, an online editor that allows you to write and test API specifications directly. This greatly simplifies the creation and customization of documentation.
Swagger Codegen, a tool for generating API client libraries and server stubs from a Swagger specification. This enables support for various programming languages and facilitates automatic code generation.
Swagger for various frameworks, such as:
- Node.js (Express.js): Installation with npm install swagger-ui-express
- Spring Boot (Java): Integration with springfox-swagger2
- Python (Flask): Using flasgger

Setup

After installation, Swagger must be integrated into the project. The integration depends on the environment used. In an Express.js application, the integration looks, for example, as follows:

const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');
const app = require('express')();

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

app.listen(3000, () => console.log('Server is running on port 3000'));

Once the application has started, the API documentation can be accessed in the browser at http://localhost:3000/api-docs. There, all endpoints are clearly displayed and can be tested interactively.

Creating Swagger API Endpoints: First Steps

To document an API with Swagger, a Swagger 2.0 specification must be created. This can be written in YAML or JSON and describes the API endpoints in detail. In doing so, not only are the available routes defined, but also the expected parameters and response structures are specified.

A simple example of an API endpoint could look as follows:

swagger: '2.0'
info:
  title: Example API
  description: A simple API to demonstrate Swagger
  version: 1.0.0
host: localhost:3000
schemes:
  - http
paths:
  /users:
    get:
      summary: Retrieve list of all users
      produces:
        - application/json
      responses:
        '200':
          description: Successful response
          schema:
            type: array
            items:
              type: object
              properties:
                id:
                  type: integer
                name:
                  type: string

Components: Reusable Definitions

Swagger enables the reuse of components such as schemas, parameters, and responses to ensure a consistent and maintainable API documentation. The components section in OpenAPI 3.0 corresponds to the definitions section in Swagger 2.0.

An example of reusing definitions:

swagger: '2.0'
info:
  title: API with Reusable Components
  version: 1.0.0
host: localhost:3000
schemes:
  - http
definitions:
  User:
    type: object
    properties:
      id:
        type: integer
      name:
        type: string
paths:
  /users:
    get:
      summary: Retrieve list of all users
      produces:
        - application/json
      responses:
        '200':
          description: Successful response
          schema:
            type: array
            items:
              $ref: '#/definitions/User'

Here, the User schema is defined in the definitions section and then reused in the response of the /users endpoint. Changes to this schema affect all endpoints that reference this definition, thereby maintaining consistency. However, modifications should be made with caution to avoid unexpected impacts on existing API clients. This approach ensures better maintainability, as changes need to be made in only one place.

Security: API Authentication and Authorization

A well-secured API is essential to prevent unauthorized access. It is important to distinguish between authentication and authorization. Authentication ensures that a user or system is indeed who they claim to be (e.g., via API keys or OAuth2), while authorization determines which actions an authenticated user is allowed to perform (e.g., read or write permissions). Swagger 2.0 supports various authentication methods, including API keys, OAuth2, and Basic Authentication.

An example of an API secured with an API key:

swagger: '2.0'
info:
  title: Secured API
  version: 1.0.0
host: localhost:3000
schemes:
  - http
securityDefinitions:
  ApiKeyAuth:
    type: apiKey
    in: header
    name: X-API-Key
paths:
  /secure-data:
    get:
      summary: Retrieve secured data
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Successful response
          schema:
            type: object
            properties:
              data:
                type: string

OAuth 2.0 Authentication

A modern and flexible method for authentication is OAuth 2.0. It allows users to securely authenticate with the API.

securityDefinitions:
  OAuth2:
    type: oauth2
    flow: accessCode
    authorizationUrl: https://example.com/oauth/authorize
    tokenUrl: https://example.com/oauth/token
    scopes:
      read: Access to secured resources
paths:
  /user-info:
    get:
      summary: Retrieve user information
      security:
        - OAuth2:
            - read
      responses:
        '200':
          description: Successful response
          schema:
            type: object
            properties:
              username:
                type: string

This ensures that the /user-info endpoint is only accessible to authenticated users with the corresponding OAuth2 token. is accessible. The scope read allows users to access protected resources read access to protected resources without making any changes. This is suitable for endpoints that provide sensitive but unchangeable information, such as such as profile data or system status.

An example of an API secured with an API key:

swagger: '2.0'
info:
  title: Secured API
  version: 1.0.0
host: localhost:3000
schemes:
  - http
securityDefinitions:
  ApiKeyAuth:
    type: apiKey
    in: header
    name: X-API-Key
paths:
  /secure-data:
    get:
      summary: Retrieve secured data
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Successful response
          schema:
            type: object
            properties:
              data:
                type: string

Best Practices for Well-Structured API Documentation

To design optimal API documentation, several best practices should be followed:

Consistent Structure: Well-organized API documentation facilitates understanding and ensures uniform documentation of all endpoints. This can be encapsulated in the form of API design guidelines, which, among other things, establish conventions for naming, versioning, and security aspects.
Descriptive Details: Each endpoint should include detailed descriptions so that users can immediately understand how it works. For example, the /users endpoint might be accompanied by the description Returns a list of all registered users. Optionally, it can be filtered by specific names using a query parameter. This helps developers better understand the purpose and potential applications of the endpoint.
Provide Sample Data: By using example or examples, a realistic impression of API responses can be conveyed. For instance, an endpoint that returns user information could include a sample response with id: 1 and name: 'John Doe' to illustrate the expected data structure.
Specify Authentication: If authentication is required, it should be clearly documented, for example by using API keys or OAuth. API keys are easy to implement and are well-suited for server-side applications, but they can be insecure if exposed in client applications. OAuth provides a more secure authentication mechanism with token-based access, though it is more complex to implement and requires additional infrastructure such as an authorization server.
Version Control: An API evolves over time. Clear versioning ensures that users are always using the correct documentation. For instance, an API version can be defined in the URL (e.g., /v1/users) or through the info.version attribute in Swagger (e.g., version: '1.0.0'). This helps to support older versions and introduce new features gradually. Using Semantic Versioning (SemVer) (MAJOR.MINOR.PATCH) enables developers to communicate changes transparently, for example, an increase in the major version (e.g., v2.0.0) indicates breaking changes, while minor updates (e.g., v1.1.0) add new features without breaking changes.
Utilize Reusable Components: Frequently used elements such as schemas, parameters, or responses should be stored in definitions (in Swagger 2.0). This makes the API documentation more consistent and easier to maintain. Swagger allows for various types of definitions, including definitions for data models, parameters for reusable parameters, responses for predefined API responses, and securityDefinitions for authentication. For example, a user structure can be defined once and referenced multiple times: $ref: '#/definitions/User'.
Use an Interactive Swagger UI: An interactive documentation makes it easier for developers to test the API and reduces the communication overhead.

Conclusion

With these steps and proven methods, a professional API documentation using Swagger 2.0 is achievable. Well-maintained and well-structured API documentation not only facilitates implementation for developers but also improves collaboration with other teams, promotes maintainability, and increases the transparency of API usage. A well-structured documentation is an essential component of any API development, as it not only assists developers but also enhances team collaboration.