Swagger UI

beginner

API documentation and testing interface.

Overview

Swagger UI is an open-source tool developed by SmartBear Software that automatically generates interactive API documentation from OpenAPI (formerly Swagger) specifications. It transforms static API documentation into a dynamic, web-based interface where developers can explore endpoints, understand request/response schemas, and execute live API calls directly from the browser. This eliminates the need for separate API testing tools during development and documentation phases. This Docker deployment serves the Swagger UI application with a pre-configured OpenAPI specification file, creating an instant API documentation portal. The container mounts your OpenAPI JSON file and serves it through the Swagger UI interface, providing immediate visualization of your API structure, request parameters, response formats, and authentication requirements. The setup includes configurable base URL support for deployment behind reverse proxies and load balancers. This configuration is ideal for development teams, API product managers, and organizations that need to provide comprehensive API documentation to internal developers or external partners. Unlike hosted solutions, this self-contained deployment gives you complete control over your API documentation, supports private APIs, and can be integrated into CI/CD pipelines for automated documentation updates whenever your API specifications change.

Key Features

Interactive API explorer with Try It Out functionality for live endpoint testing
Automatic rendering of OpenAPI 3.0 and Swagger 2.0 specification files
OAuth2, API key, and HTTP authentication support for testing secured endpoints
Real-time request/response validation against API schema definitions
Customizable theme and branding options for corporate documentation portals
Deep-linking support for sharing specific API endpoints and operations
Responsive design optimized for desktop and mobile API documentation viewing
Request/response model visualization with expandable schema definitions

Common Use Cases

1Development teams documenting REST APIs for internal microservices architecture
2Product companies providing interactive API documentation for third-party developers
3Enterprise organizations creating API catalogs for cross-team service discovery
4Startup teams building API-first products requiring investor or partner demonstrations
5DevOps engineers setting up documentation for CI/CD pipeline API endpoints
6QA teams using interactive testing interface for API validation workflows
7Technical writers creating comprehensive API guides with live examples

Prerequisites

Valid OpenAPI 2.0 or 3.0 specification file in JSON or YAML format
Docker Engine 20.10+ and Docker Compose 2.0+ installed on host system
Port 8080 available on host machine for web interface access
At least 128MB RAM available for container operation
Basic understanding of OpenAPI specification structure and API documentation
Network access to target API endpoints if testing live APIs through the interface

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  swagger-ui: 
3    image: swaggerapi/swagger-ui:latest
4    container_name: swagger-ui
5    restart: unless-stopped
6    environment: 
7      SWAGGER_JSON: /api/openapi.json
8      BASE_URL: /swagger
9    volumes: 
10      - ./openapi.json:/api/openapi.json:ro
11    ports: 
12      - "8080:8080"

.env Template

.env

1# Mount your OpenAPI spec as openapi.json

Usage Notes

1Docs: https://swagger.io/tools/swagger-ui/
2Access at http://localhost:8080 - view API documentation
3Mount OpenAPI spec as /api/openapi.json
4Try It Out button for interactive API testing
5BASE_URL sets path prefix for reverse proxy deployments
6Supports OAuth2 authentication for testing secured endpoints

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  swagger-ui:
5    image: swaggerapi/swagger-ui:latest
6    container_name: swagger-ui
7    restart: unless-stopped
8    environment:
9      SWAGGER_JSON: /api/openapi.json
10      BASE_URL: /swagger
11    volumes:
12      - ./openapi.json:/api/openapi.json:ro
13    ports:
14      - "8080:8080"
15EOF
16
17# 2. Create the .env file
18cat > .env << 'EOF'
19# Mount your OpenAPI spec as openapi.json
20EOF
21
22# 3. Start the services
23docker compose up -d
24
25# 4. View logs
26docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/swagger-ui/run | bash

Troubleshooting

Swagger UI shows 'Failed to load spec' error: Verify openapi.json file exists in mounted directory and contains valid JSON syntax
API endpoints return CORS errors during testing: Configure your API server to allow requests from Swagger UI origin or disable CORS validation
OAuth2 authentication not working: Ensure OAuth2 configuration in OpenAPI spec includes correct authorization URLs and scopes
Container fails to start with permission errors: Check file permissions on mounted openapi.json file and ensure Docker has read access
Swagger UI displays but API operations are missing: Validate OpenAPI specification against OpenAPI 3.0 schema using online validators
Custom BASE_URL not working behind reverse proxy: Ensure proxy passes correct headers and BASE_URL matches your proxy path configuration

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

swagger-ui

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download