Swagger UI - Interactive API Documentation

Swagger UI is the most popular open-source tool for visualizing and interacting with APIs. It transforms OpenAPI (formerly Swagger) specifications into beautiful, interactive HTML documentation that allows developers to explore API endpoints, test requests, and understand API behavior — all without writing a single line of code.

Key Features:

• Interactive Documentation: Visual API exploration with try-it-out functionality
• OpenAPI Support: Full support for OpenAPI 2.0, 3.0.x, 3.1.x, and 3.2.0 specifications
• Multiple Installation Options: NPM package, Docker container, or vanilla HTML/JS
• Customizable UI: Plugin system for extending functionality and theming
• OAuth2 Support: Built-in authentication flow for protected APIs
• Vendor Extensions: Support for custom vendor-specific extensions
• Deep Linking: Direct links to specific operations or parameters
• Responsive Design: Works on desktop and mobile devices

Use Cases:

• API Documentation: Automatically generate API docs from OpenAPI specs
• API Testing: Try API endpoints directly in the browser
• Developer Onboarding: Help developers understand your API quickly
• API Debugging: Inspect responses and troubleshoot issues
• Client Code Generation: Download SDK/client code in various languages

Who Should Use It:

• API developers who need to document their services
• Frontend developers consuming APIs
• API consumers who need to test endpoints
• Technical writers creating API documentation
• DevOps teams deploying API documentation

Official Website: https://swagger.io/tools/swagger-ui/
GitHub: https://github.com/swagger-api/swagger-ui (28.8k stars)
Documentation: https://github.com/swagger-api/swagger-ui/blob/master/docs
NPM Package: https://www.npmjs.com/package/swagger-ui

Swagger UI publishes three NPM modules for different use cases:

Modules:

1. swagger-ui: For JavaScript web projects with bundlers (Webpack, Browserify, Rollup). Smallest bundle size.
2. swagger-ui-dist: Dependency-free bundle with all assets. For server-side projects or apps without bundlers.
3. swagger-ui-react: Pure React component for integration in React applications.

Recommendation: Use swagger-ui when you have a bundler. It's ~5x smaller than swagger-ui-dist at runtime.

Installation:

• swagger-ui: Core module with dependency resolution (recommended for SPAs)
• swagger-ui-dist: All-in-one bundle with static files (easiest for quick start)
• swagger-ui-react: React component for embedding in React apps

# Option 1: Core module (recommended for web apps with bundlers)
npm install swagger-ui

# Option 2: All-in-one bundle with static files
npm install swagger-ui-dist

# Option 3: React component
npm install swagger-ui-react

When using the swagger-ui module with a bundler like Webpack, you get a smaller bundle and proper dependency resolution.

Basic Setup:

1. Import from swagger-ui
2. Create a DOM element for the UI
3. Initialize with your OpenAPI spec URL

// Import Swagger UI
import SwaggerUI from 'swagger-ui'

// Import the stylesheet
import 'swagger-ui/dist/swagger-ui.css'

// Initialize Swagger UI
const ui = SwaggerUI({
  url: 'https://petstore3.swagger.io/api/v3/openapi.json',
  dom_id: '#swagger-ui',
  presets: [
    SwaggerUI.presets.apis,
    SwaggerUI.SwaggerUIStandalonePreset
  ],
  layout: 'StandaloneLayout'
})

Swagger UI can be run as a Docker container, making it easy to deploy API documentation in any environment.

Features:

• Pre-configured Nginx server
• Environment variables for customization
• Supports local file mounting or remote URLs
• Production-ready deployment

# Pull the official Docker image
docker pull docker.swagger.io/swaggerapi/swagger-ui

# Run with default configuration
docker run -p 80:8080 docker.swagger.io/swaggerapi/swagger-ui

# Mount your local OpenAPI spec file
docker run -p 80:8080 \
  -e SWAGGER_JSON=/swagger.json \
  -v $(pwd)/openapi.json:/swagger.json \
  docker.swagger.io/swaggerapi/swagger-ui

# Use a remote URL for your OpenAPI spec
docker run -p 80:8080 \
  -e SWAGGER_JSON_URL=https://petstore3.swagger.io/api/v3/openapi.json \
  docker.swagger.io/swaggerapi/swagger-ui

Quickly embed Swagger UI in any HTML page using unpkg CDN. No installation required.

Use Cases:

• Static HTML pages
• Quick demos
• Simple websites
• When you need instant setup

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>My API Documentation</title>
    <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@latest/swagger-ui.css" />
  </head>
  <body>
    <div id="swagger-ui"></div>
    <script src="https://unpkg.com/swagger-ui-dist@latest/swagger-ui-bundle.js" crossorigin></script>
    <script>
      window.onload = () => {
        window.ui = SwaggerUIBundle({
          url: 'https://petstore3.swagger.io/api/v3/openapi.json',
          dom_id: '#swagger-ui'
        });
      };
    </script>
  </body>
</html>

Swagger UI is highly configurable. Here are the most common configuration options:

Key Configuration Options:

• url: URL to your OpenAPI spec
• dom_id: HTML element ID to mount UI
• spec: Inline OpenAPI spec object
• validatorUrl: URL for spec validator (set to '' to disable)
• displayOperationId: Show operation IDs
• showExtensions: Show vendor extensions

// Basic configuration
SwaggerUI({
  url: 'https://petstore3.swagger.io/api/v3/openapi.json',
  dom_id: '#swagger-ui',
  displayOperationId: true,
  displayRequestDuration: true,
  showExtensions: true,
  showCommonExtensions: true,
  filter: true,
  docExpansion: 'list',
  deepLinking: true,
  presets: [
    SwaggerUI.presets.apis,
    SwaggerUI.SwaggerUIStandalonePreset
  ],
  layout: 'StandaloneLayout'
})

Swagger UI supports OAuth2 authentication flows for testing protected APIs.

Supported Flows:

• Authorization Code Flow
• Implicit Flow
• Client Credentials Flow (via request interceptor)

Configuration:

1. Define oauth2 options in your configuration
2. Configure your OAuth2 provider
3. Use oauth2-redirect.html for callbacks

// OAuth2 configuration
SwaggerUI({
  url: 'https://petstore3.swagger.io/api/v3/openapi.json',
  dom_id: '#swagger-ui',
  oauth2: {
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
    realm: 'your-realm',
    appName: 'Your App Name',
    scopes: 'read:api write:api admin'
  },
  oauth2RedirectUrl: 'oauth2-redirect.html'
})

Integrate Swagger UI directly into your Node.js applications to serve API documentation alongside your API.

Popular Frameworks:

• Express (swagger-ui-express)
• Koa (koa-swagger-ui)
• Fastify (@fastify/swagger + @fastify/swagger-ui)
• NestJS (@nestjs/swagger)

// Express.js with swagger-ui-express
const express = require('express')
const swaggerUi = require('swagger-ui-express')
const YAML = require('yamljs')

const app = express()

// Load OpenAPI spec
const openapiSpecification = YAML.load('./openapi.yaml')

// Mount Swagger UI
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(openapiSpecification, {
  explorer: true,
  customCss: '.swagger-ui .topbar { display: none }',
  customSiteTitle: 'My API Docs'
}))

app.listen(3000)