Skip to content

Swagger UI — Interactive API Documentation from OpenAPI Specs

DodaTech Updated 2026-06-28 2 min read

In this tutorial, you will learn about Swagger UI. We cover key concepts, practical examples, and best practices to help you master this topic.

Swagger UI is a tool that generates interactive HTML documentation from OpenAPI specifications, providing a visual interface for exploring and testing API endpoints.

What You'll Learn

  • Setting up Swagger UI for your API
  • Customizing the Swagger UI theme and branding
  • Hosting Swagger UI with various deployment options

Why It Matters

Swagger UI is the most popular API documentation tool. It turns your OpenAPI spec into an interactive playground that developers can use immediately.

Code Examples

<!-- Self-hosted Swagger UI -->
<!DOCTYPE html>
<html>
<head>
  <title>API Documentation</title>
  <link rel="stylesheet"
    href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css">
</head>
<body>
  <div id="swagger-ui"></div>
  <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js">
  </script>
  <script>
    SwaggerUIBundle({
      url: "/openapi.yaml",
      dom_id: "#swagger-ui",
      presets: [
        SwaggerUIBundle.presets.apis,
        SwaggerUIBundle.SwaggerUIStandalonePreset
      ],
      layout: "StandaloneLayout",
      supportedSubmitMethods: ["get", "post"]
    });
  </script>
</body>
</html>

// Swagger UI with custom configuration
const ui = SwaggerUIBundle({
  url: "/openapi.yaml",
  dom_id: "#swagger-ui",
  deepLinking: true,
  displayOperationId: true,
  defaultModelsExpandDepth: 1,
  defaultModelExpandDepth: 1,
  docExpansion: "list",
  filter: true,
  showExtensions: true,
  showCommonExtensions: true,
  tryItOutEnabled: true
});

# Flask serving Swagger UI
from flask import Flask, send_from_directory

app = Flask(__name__)

@app.route('/docs')
def swagger_ui():
    return send_from_directory('static', 'swagger.html')

@app.route('/openapi.yaml')
def openapi_spec():
    return send_from_directory('static', 'openapi.yaml')

Common Mistakes

1. Using Outdated Swagger UI Version

Always use the latest Swagger UI for security fixes and new features.

2. Not Enabling Try-It-Out

The interactive console is Swagger UI's killer feature. Enable it.

3. Missing CORS Configuration

Swagger UI needs CORS headers to make test requests to your API.

4. No Authentication Support

Configure Swagger UI to support your API's auth methods.

5. Serving Spec from Different Origin

OpenAPI spec and Swagger UI must be served from the same origin or with CORS.

Practice Questions

  1. What format does Swagger UI read for documentation?
  2. How do you enable the Try-It-Out feature?
  3. What is required for Swagger UI to make test API calls?
  4. How do you customize Swagger UI branding?
  5. What is the difference between Swagger UI and Redoc?

Answers:

  1. OpenAPI (YAML or JSON) specification.
  2. It's enabled by default in modern versions.
  3. The API must support CORS or be on the same origin.
  4. By passing configuration options or using CSS overrides.
  5. Swagger UI is interactive; Redoc is a static, clean, non-interactive viewer.

Challenge: Set up Swagger UI for a sample API. Customize the theme colors, enable deep linking, and add authentication support.

FAQ

Is Swagger UI free to use?

: Yes. Swagger UI is open source under the Apache 2.0 license.

Can I brand Swagger UI with my company logo?

: Yes, through custom CSS and configuration.

Does Swagger UI support OAuth2?

: Yes. It can handle OAuth2 flows for authenticated API testing.

← Previous OpenAPI Security — Defining Authentication and Authorization Next → Redoc — Beautiful Static API Documentation from OpenAPI

Built by the developers of DodaTech

Doda Browser, DodaZIP & Durga Antivirus Pro

Home Browse Api Documentation