Using Swagger UI to Visualize API Documentation

In this article, we'll explore how Swagger UI can help you visualize and interact with your API documentation effectively. Learn how to set up Swagger UI and leverage its features to create a more user-friendly documentation experience.
By Jamie
  • Setting up Swagger UI
  • Visualizing API endpoints
  • Interacting with the API through the UI

1. Setting Up Swagger UI

To get started with Swagger UI, you first need to include the Swagger UI library in your project. Here’s a simple example of how to set it up:

HTML Setup

<!DOCTYPE html>
<html>
<head>
    <title>Swagger UI Example</title>
    <link rel="stylesheet" type="text/css" href="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.52.5/swagger-ui.css" />
    <script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.52.5/swagger-ui-bundle.js"></script>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.52.5/swagger-ui-standalone-preset.js"></script>
</head>
<body>
    <div id="swagger-ui"></div>
    <script>
        const ui = SwaggerUIBundle({
            url: "https://your-api-endpoint/swagger.json",
            dom_id: '#swagger-ui',
            presets: [SwaggerUIStandalonePreset],
            layout: "BaseLayout",
        });
    </script>
</body>
</html>

In this code snippet:

  • We include the Swagger UI CSS and JavaScript files from a CDN.
  • We create a div with an ID of swagger-ui where the documentation will be rendered.
  • We initialize the Swagger UI with the API endpoint that serves the Swagger specification (usually a JSON file).

2. Visualizing API Endpoints

Once you set up Swagger UI, it automatically generates a visual representation of your API based on the provided Swagger JSON file. Here’s an example of how the API documentation might look:

  • GET /users

    • Description: Retrieves a list of users.

    • Response: 200 OK

      • Content:

        [{
    "id": 1,
    "name": "John Doe"
}, {
    "id": 2,
    "name": "Jane Smith"
}]

  • POST /users

    • Description: Creates a new user.

    • Request Body:

      {
    "name": "New User"
}

    • Response: 201 Created

      • Content:
      {
    "id": 3,
    "name": "New User"
}

3. Interacting with the API through the UI

Swagger UI not only visualizes your API but also allows you to interact with it directly from the interface. For example:

  • To test the GET /users endpoint:
    1. Click on the endpoint in Swagger UI.
    2. Click the Try it out button.
    3. Click the Execute button.

The UI will display the response received from your API, including the status code and response body.

Conclusion

Swagger UI is an invaluable tool for API developers and consumers alike, providing a clear and interactive way to explore and test APIs. By integrating Swagger UI into your API documentation, you enhance usability and improve the developer experience.