The Project | About Us | Contribute | Donations | License
HOME My courses Completed
◄ Previous
◄

Swagger for Documentation

Next ►
►

Swagger is a powerful toolset for API documentation and design. It provides a comprehensive framework for describing, producing, consuming, and visualizing RESTful web services. Swagger's primary goal is to enable developers to design and document APIs efficiently and effectively.

What is Swagger?

Swagger is an open-source framework backed by a large ecosystem of tools that help you design, build, document, and consume RESTful web services. It uses a standard, language-agnostic interface to REST APIs which allows both humans and computers to understand the capabilities of a service without access to source code, documentation, or through network traffic inspection.

Key Components of Swagger

  1. Swagger Editor: An online tool for writing and visualizing OpenAPI definitions.
  2. Swagger UI: A collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.
  3. Swagger Codegen: A tool that generates client libraries, server stubs, API documentation, and configuration automatically given an OpenAPI Specification.

Why Use Swagger?

  • Interactive Documentation: Swagger UI allows users to interact with the API directly from the documentation.
  • Standardization: Swagger uses the OpenAPI Specification, which is a widely adopted standard for API documentation.
  • Automation: Tools like Swagger Codegen can automatically generate client libraries and server stubs, reducing manual coding effort.
  • Ease of Use: Swagger Editor provides a user-friendly interface for creating and editing API specifications.

Setting Up Swagger

Step 1: Install Swagger UI

To use Swagger UI, you can either download the distribution files and host them yourself or use a CDN. Here’s how you can set it up using npm:

npm install -g http-server
mkdir swagger-ui
cd swagger-ui
curl -o swagger-ui.zip https://github.com/swagger-api/swagger-ui/archive/master.zip
unzip swagger-ui.zip
http-server swagger-ui-master/dist

Step 2: Create an OpenAPI Specification

The OpenAPI Specification (formerly known as Swagger Specification) is a standard way to describe REST APIs. Here’s a basic example of an OpenAPI Specification in YAML format:

openapi: 3.0.0
info:
  title: Sample API
  description: API description in Markdown.
  version: 1.0.0
servers:
  - url: http://api.example.com/v1
paths:
  /users:
    get:
      summary: Returns a list of users.
      responses:
        '200':
          description: A JSON array of user names
          content:
            application/json:
              schema: 
                type: array
                items: 
                  type: string

Step 3: Serve the OpenAPI Specification with Swagger UI

Place the OpenAPI Specification file (e.g., openapi.yaml) in the swagger-ui-master/dist directory and modify the index.html file to point to your specification:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Swagger UI</title>
  <link rel="stylesheet" type="text/css" href="https://unpkg.com/swagger-ui-dist/swagger-ui.css" />
</head>
<body>
  <div id="swagger-ui"></div>
  <script src="https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"></script>
  <script>
    const ui = SwaggerUIBundle({
      url: "openapi.yaml",
      dom_id: '#swagger-ui',
    });
  </script>
</body>
</html>

Step 4: View the Documentation

Run the HTTP server and navigate to http://localhost:8080 in your browser. You should see the Swagger UI with your API documentation.

Practical Exercise

Exercise: Document a Simple API

  1. Objective: Create an OpenAPI Specification for a simple API that manages a list of books.
  2. Steps:
    • Define the API title, description, and version.
    • Specify the server URL.
    • Create paths for the following operations:
      • GET /books: Retrieve a list of books.
      • POST /books: Add a new book.
      • GET /books/{id}: Retrieve a book by ID.
      • PUT /books/{id}: Update a book by ID.
      • DELETE /books/{id}: Delete a book by ID.

Solution

Here’s a sample OpenAPI Specification for the books API:

openapi: 3.0.0
info:
  title: Books API
  description: API for managing a list of books.
  version: 1.0.0
servers:
  - url: http://api.example.com/v1
paths:
  /books:
    get:
      summary: Retrieve a list of books.
      responses:
        '200':
          description: A list of books.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Book'
    post:
      summary: Add a new book.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Book'
      responses:
        '201':
          description: Book created.
  /books/{id}:
    get:
      summary: Retrieve a book by ID.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A single book.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'
    put:
      summary: Update a book by ID.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Book'
      responses:
        '200':
          description: Book updated.
    delete:
      summary: Delete a book by ID.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Book deleted.
components:
  schemas:
    Book:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        author:
          type: string
        publishedDate:
          type: string
          format: date

Conclusion

Swagger is an invaluable tool for API documentation, providing a standardized and interactive way to describe and consume RESTful APIs. By following the steps outlined in this section, you can set up Swagger UI and create comprehensive documentation for your APIs. This not only improves the developer experience but also ensures that your APIs are well-documented and easy to understand.

In the next module, we will explore popular frameworks for developing RESTful APIs and how they integrate with tools like Swagger.

◄ Previous
◄
Next ►
►
The Project | About Us | Contribute | Donations | License
© Copyright 2024. All rights reserved