Examples of Swagger API Documentation

Introduction to Swagger API Documentation

Swagger is an open-source tool that helps developers design, build, document, and consume RESTful Web services. By providing a standardized way to describe APIs, it enhances communication between developers and stakeholders. Below are three diverse examples of Swagger API documentation that illustrate how to effectively document your APIs.

1. User Authentication API

Context

In a typical web application, user authentication is crucial for securing user data. This example documents an API endpoint responsible for user login, including parameters and expected responses.

swagger: "2.0"
info:
  title: User Authentication API
  version: 1.0.0
paths:
  /auth/login:
    post:
      summary: Logs a user into the system
      parameters:

        - name: username
          in: body
          required: true
          type: string
          description: The username of the user

        - name: password
          in: body
          required: true
          type: string
          description: The password of the user
      responses:
        200:
          description: Successful login
          schema:
            type: object
            properties:
              token:
                type: string
                description: JWT token for subsequent requests
        401:
          description: Unauthorized - invalid credentials
        500:
          description: Server error

Notes

• Ensure that the password is transmitted securely (e.g., via HTTPS).
• Consider implementing rate limiting to protect against brute-force attacks.

2. Product Inventory API

Context

For e-commerce platforms, managing product inventory is essential. This example documents an API endpoint for retrieving product details, including query parameters and response formats.

swagger: "2.0"
info:
  title: Product Inventory API
  version: 1.0.0
paths:
  /products:
    get:
      summary: Retrieve a list of products
      parameters:

        - name: category
          in: query
          required: false
          type: string
          description: Filter products by category

        - name: limit
          in: query
          required: false
          type: integer
          description: Limit the number of products returned
      responses:
        200:
          description: A list of products
          schema:
            type: array
            items:
              type: object
              properties:
                id:
                  type: integer
                  description: Product ID
                name:
                  type: string
                  description: Product name
                price:
                  type: number
                  format: float
                  description: Product price
        400:
          description: Bad request
        500:
          description: Server error

Notes

• Pagination can be added by implementing offset and limit parameters.
• Consider adding caching mechanisms to improve performance.

3. Weather Forecast API

Context

Weather applications often need to provide users with real-time data. This example documents an API endpoint that provides weather forecasts based on geographical coordinates.

swagger: "2.0"
info:
  title: Weather Forecast API
  version: 1.0.0
paths:
  /weather/forecast:
    get:
      summary: Get weather forecast by location
      parameters:

        - name: lat
          in: query
          required: true
          type: number
          description: Latitude of the location

        - name: lon
          in: query
          required: true
          type: number
          description: Longitude of the location
      responses:
        200:
          description: Weather forecast details
          schema:
            type: object
            properties:
              temperature:
                type: number
                description: Current temperature
              humidity:
                type: integer
                description: Current humidity percentage
              forecast:
                type: string
                description: Forecast description (e.g., sunny, rainy)
        404:
          description: Location not found
        500:
          description: Server error

Notes

• Implement error handling to manage invalid coordinates.
• Consider integrating with third-party weather data providers for accuracy.