Skip to content

Swagger UI — Rendering Interactive API Documentation

DodaTech Updated 2026-06-28 5 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 renders OpenAPI specifications as interactive web pages that let developers explore endpoints, view schemas, and make test requests directly from the browser.

In this tutorial, you will learn how to set up Swagger UI, customize its appearance, configure it for production use, and integrate it with your API deployment pipeline.

What You'll Learn

You will learn installation options for Swagger UI, configuration settings for branding and behavior, how to customize the appearance, and how to deploy it in production alongside your API.

Why It Matters

Swagger UI is the most widely used OpenAPI visualization tool. It transforms a static YAML file into an interactive developer experience with zero additional coding. Every API provider should know how to deploy and customize it.

Real-World Use

DodaTech uses Swagger UI for internal API documentation. Each microservice has a /docs endpoint that serves Swagger UI pointing to its OpenAPI spec. Developers use the interactive console for testing during development and debugging.

flowchart LR
  A[OpenAPI Spec] --> B[Swagger UI]
  B --> C[Interactive Docs]
  C --> D[API Console]
  C --> E[Schema Browser]
  C --> F[Code Samples]
  B:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Installation Options

Docker

The simplest way to run Swagger UI:

docker run -p 8080:8080 \
  -e SWAGGER_JSON=/spec/openapi.yaml \
  -v $(pwd):/spec \
  swaggerapi/swagger-ui

NPM Package

Embed Swagger UI in a Node.js application:

npm install swagger-ui

const SwaggerUI = require("swagger-ui");
const express = require("express");
const app = express();

app.get("/docs", (req, res) => {
  res.send(`
    <!DOCTYPE html>
    <html>
    <head>
      <title>DodaTech API Documentation</title>
      <link rel="stylesheet" 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>
        SwaggerUI({
          dom_id: "#swagger-ui",
          url: "/openapi.yaml",
        });
      </script>
    </body>
    </html>
  `);
});

app.use(express.static("public"));
app.listen(3000);

CDN

The fastest way to try Swagger UI:

<!DOCTYPE html>
<html>
<head>
  <title>API Docs</title>
  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.17.0/swagger-ui.min.css">
</head>
<body>
  <div id="swagger-ui"></div>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.17.0/swagger-ui-bundle.min.js"></script>
  <script>
    SwaggerUI({
      dom_id: "#swagger-ui",
      url: "https://api.dodatech.com/openapi.yaml",
      defaultModelsExpandDepth: 1,
      docExpansion: "list",
      filter: true,
      showExtensions: true,
      supportedSubmitMethods: ["get", "post", "put", "delete"]
    });
  </script>
</body>
</html>

Configuration Options

Key Swagger UI configuration options:

SwaggerUI({
  dom_id: "#swagger-ui",
  url: "/openapi.yaml",
  // Display options
  defaultModelsExpandDepth: -1, // Hide schemas section
  defaultModelExpandDepth: 1,
  docExpansion: "list", // "list", "full", "none"
  filter: true, // Enable endpoint search
  showExtensions: true,
  showCommonExtensions: true,
  // Try-it-out options
  supportedSubmitMethods: ["get", "post", "put", "patch", "delete"],
  tryItOutEnabled: true, // Start with Try It Out open
  // Prefill options
  requestSnippetsEnabled: true,
  // Branding
  persistAuthorization: true, // Remember auth tokens
  displayRequestDuration: true, // Show response time
});

Customizing Appearance

Override Swagger UI styles:

/* Custom theme for DodaTech */
.swagger-ui .topbar {
  background-color: #ff6600;
}

.swagger-ui .topbar .download-url-wrapper .select-label select {
  border-color: #ff6600;
}

.swagger-ui .btn.execute {
  background-color: #ff6600;
  border-color: #ff6600;
}

.swagger-ui .info .title {
  color: #333;
}

.swagger-ui .opblock-tag {
  font-size: 18px;
  border-bottom: 2px solid #ff6600;
}

Production Deployment

Serve Swagger UI alongside your API:

const express = require("express");
const swaggerUi = require("swagger-ui-express");
const YAML = require("yamljs");
const app = express();

const openapiSpec = YAML.load("./openapi.yaml");

app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(openapiSpec, {
  customSiteTitle: "DodaTech API Docs",
  customfavIcon: "/favicon.ico",
  customCss: ".topbar { display: none }",
  swaggerOptions: {
    persistAuthorization: true,
    displayRequestDuration: true
  }
}));

// Redirect root to docs
app.get("/", (req, res) => {
  res.redirect("/api-docs");
});

app.listen(3000);

Common Mistakes

  1. Serving outdated specs — Swagger UI caches the spec file. Set cache headers or use a versioned URL to ensure developers always see the latest docs.

  2. No CORS configuration — The Try It Out console makes requests from the browser. Configure CORS headers on your API to allow the Swagger UI origin.

  3. Exposing sensitive endpoints in production — Using Swagger UI with the production API URL. Use a separate spec for internal vs external documentation.

  4. No authentication prefill — Not configuring persistAuthorization. Developers must re-enter tokens on every page reload.

  5. Too many schemas expanded by default — Setting defaultModelsExpandDepth too high slows page load. Use -1 to hide schemas or 1 to show top level only.

Practice Questions

  1. What are three ways to deploy Swagger UI?
  2. How do you enable the Try It Out feature in Swagger UI?
  3. How do you customize the Swagger UI theme colors?
  4. What CORS considerations are needed for Swagger UI?
  5. How do you persist authentication tokens across page reloads?

Challenge

Set up a complete Swagger UI deployment for a sample API. Configure custom branding with your company colors, enable Try It Out with a pre-filled API key, hide the schema section, add a custom favicon, and deploy behind an Express server with CORS support.

FAQ

Can Swagger UI work with multiple OpenAPI specs?

Swagger UI loads one spec at a time. Use the topbar dropdown to switch between specs, or create separate Swagger UI instances for each spec.

How do I secure Swagger UI in production?

Use authentication middleware on the /docs route. Require a login to view internal API documentation. For public APIs, Swagger UI can be unauthenticated.

Does Swagger UI support OpenAPI 3.1?

Yes. Swagger UI v5 and later fully support OpenAPI 3.1. Use the latest version for full compatibility.

How do I add code samples to Swagger UI?

Swagger UI auto-generates code samples from your spec. Define x-codeSamples in your OpenAPI spec for custom examples in specific languages.

Can I disable the Try It Out button?

Yes. Set supportedSubmitMethods: [] to disable Try It Out entirely, or list only specific methods like ["get"].

Mini Project

Create a branded Swagger UI deployment for a notes API. Customize the CSS with your brand colors, configure persistent authorization, enable request snippets, set up CORS on the API server, and deploy using Docker with a versioned spec file.

What's Next

In the next lesson, you will learn about Redoc, an alternative documentation renderer with a clean, three-panel layout.

← Previous OpenAPI Security — Defining Authentication and Authorization Next → Redoc — Clean API Documentation with Three-Panel Layout

Built by the developers of DodaTech

Doda Browser, DodaZIP & Durga Antivirus Pro

Home Browse Api Documentation