swagger-ui-python 1.0.0

Swagger UI for Python web framework, such as Tornado, Flask, Quart, Sanic and Falcon.

Project Page | Documentation

swagger-ui-py

Seamless Swagger UI integration for Python web frameworks. A unified, framework-agnostic API for adding interactive OpenAPI documentation to your Python applications with automatic framework detection.

Status: Production-ready, actively maintained Python: 3.9, 3.10, 3.11, 3.12 Swagger UI: v5.25.3 Swagger Editor: v4.14.6

Key Features

• Framework Agnostic - Single API works across 9+ Python frameworks
• Auto-Detection - Automatically detects your framework, zero configuration needed
• Multiple Config Sources - YAML/JSON files, remote URLs, Python dicts, or strings
• Swagger Editor - Optional inline spec editor for live documentation editing
• Static Assets - Automatic CSS, JS, images, and icons serving
• Customization - Custom CSS, Swagger UI parameters, OAuth2 configuration
• Well-Tested - 50+ test cases across all supported frameworks

Supported Frameworks

• Tornado
• Flask
• Sanic
• AIOHTTP
• Quart
• Starlette
• Falcon
• Bottle
• Chalice

Check supported frameworks:

python3 -c "from swagger_ui import supported_list; print(supported_list)"
# Output: ['flask', 'tornado', 'sanic', 'aiohttp', 'quart', 'starlette', 'falcon', 'bottle', 'chalice']

Quick Start

Installation

pip install swagger-ui-py

Basic Example (Flask)

from flask import Flask
from swagger_ui import api_doc

app = Flask(__name__)

# Auto-detects Flask and registers routes
api_doc(app, config_path='./openapi.yaml')

if __name__ == '__main__':
    app.run(debug=True)
    # Visit: http://localhost:5000/api/doc

Basic Example (Tornado)

import tornado.ioloop
from tornado.web import Application
from swagger_ui import api_doc

app = Application()

# Auto-detects Tornado and registers routes
api_doc(app, config_path='./openapi.yaml', url_prefix='/api/doc')

if __name__ == '__main__':
    app.listen(8888)
    tornado.ioloop.IOLoop.current().start()
    # Visit: http://localhost:8888/api/doc

Configuration Options

1. Configuration Sources (in priority order)

Option A: YAML/JSON File

api_doc(app, config_path='./openapi.yaml')

Option B: Remote URL (requires CORS)

api_doc(app, config_url='https://petstore.swagger.io/v2/swagger.json')

Option C: Python Dict

config = {
    "openapi": "3.0.1",
    "info": {"title": "My API", "version": "1.0.0"},
    "paths": { ... }
}
api_doc(app, config=config)

Option D: JSON/YAML String

spec_string = '{"openapi":"3.0.1","info":{"title":"My API"},...}'
api_doc(app, config_spec=spec_string)

Option E: External Endpoint

api_doc(app, config_rel_url='/swagger.json')  # App provides endpoint

2. Common Parameters

api_doc(
    app,
    config_path='./openapi.yaml',      # Config source
    url_prefix='/api/doc',              # Internal route path (default: '/api/doc')
    base_url=None,                      # External URL for assets (defaults to url_prefix)
    title='API Documentation',          # HTML page title
    editor=False,                       # Enable spec editor
    custom_css='https://cdn.../style.css',  # Custom CSS
    host_inject=True,                   # Auto-inject request host
)

3. Reverse Proxy Support

When running behind a reverse proxy with a path prefix (e.g., ingress /service/* → backend), use base_url to set the external URL path for static assets:

# Proxy routes /service/docs/* to backend /docs/*
api_doc(
    app,
    config_path='./openapi.yaml',
    url_prefix='/docs',              # Internal routes registered at /docs
    base_url='/service/docs',        # Assets linked as /service/docs/static/*
)

• url_prefix - Used for internal route registration (app-side)
• base_url - Used for asset URLs in HTML templates (browser-side, defaults to url_prefix)

4. Swagger UI Customization

parameters = {
    "deepLinking": "true",
    "displayRequestDuration": "true",
    "layout": "\"StandaloneLayout\"",
    "plugins": "[SwaggerUIBundle.plugins.DownloadUrl]",
}
api_doc(app, config_path='./openapi.yaml', parameters=parameters)

See Swagger UI Parameters for all options.

5. OAuth2 Configuration

oauth2_config = {
    "clientId": "\"your-client-id\"",
    "clientSecret": "\"your-secret\"",
    "realm": "\"your-realm\"",
    "appName": "\"your-app\"",
    "scopeSeparator": "\" \"",
    "scopes": "\"openid profile\"",
}
api_doc(app, config_path='./openapi.yaml', oauth2_config=oauth2_config)

See OAuth2 Configuration for details.

6. Legacy Framework-Specific APIs

Still supported for backward compatibility:

from swagger_ui import flask_api_doc, tornado_api_doc, sanic_api_doc

# Same as api_doc(app, ...) but explicit
flask_api_doc(app, config_path='./openapi.yaml')
tornado_api_doc(app, config_path='./openapi.yaml')
sanic_api_doc(app, config_path='./openapi.yaml')

Routes Created

The library automatically creates these routes (at url_prefix=/api/doc):

• GET /api/doc - Interactive Swagger UI documentation
• GET /api/doc/swagger.json - OpenAPI specification (JSON)
• GET /api/doc/editor - Swagger Editor (if editor=True)
• GET /api/doc/static/{path} - Static assets (CSS, JS, images)

Creating OpenAPI Specifications

For details on writing OpenAPI specifications:

• OpenAPI 3.0 Guide
• OpenAPI 3.1 Spec
• Swagger Editor - Interactive spec editor

Versions

• Swagger UI: v5.25.3 (GitHub)
• Swagger Editor: v4.14.6 (GitHub)

To update to newer versions:

tox -e update
# or
python tools/update.py --ui-version=v5.25.3 --editor-version=v4.14.6

Extending the Library

Adding Support for New Frameworks

To add support for a new framework:

1. Create swagger_ui/handlers/{framework}.py following the handler interface
2. Implement handler(doc) and match(doc) functions
3. Add tests in test/{framework}_test.py
4. Update README with framework name
5. Auto-discovery will handle the rest

See Code Standards for detailed guidelines.

Custom Parameters & Configuration

Pass custom parameters and OAuth2 configuration through the api_doc() function for full control over Swagger UI behavior.

Documentation

Full documentation available in the ./docs directory:

• Project Overview & PDR - Vision, goals, requirements
• Codebase Summary - Module structure and responsibilities
• Code Standards - Coding conventions and patterns
• System Architecture - Design patterns and data flow
• Project Roadmap - Planned improvements and timeline

Development

Setup

# Clone repository
git clone https://github.com/PWZER/swagger-ui-py.git
cd swagger-ui-py

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
make pytest

# Format code
make format

# Build wheel
make whl

Testing

make pytest              # Run all tests
make format-check        # Check code style
make format              # Auto-format code

Building & Release

make whl                 # Build wheel
make upload              # Upload to PyPI

Troubleshooting

Framework not detected:

• Ensure framework is installed
• Try explicit app_type parameter: api_doc(app, app_type='flask', ...)

Config not loading:

• Check file path exists and is readable
• Validate YAML/JSON format using Swagger Editor
• Check CORS headers if using remote URL

Routes not registered:

• Ensure api_doc() called before app starts
• Check url_prefix doesn't conflict with existing routes
• Verify framework-specific setup (e.g., app.register_blueprint() for Flask)

For more help:

• Check examples/ directory for working samples
• Review GitHub Issues
• Read framework-specific documentation

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure tests pass: make pytest
5. Format code: make format
6. Submit a pull request

See Code Standards for contribution guidelines.

License

Licensed under the Apache License 2.0. See LICENSE file for details.

Support

• Issues: GitHub Issues
• Project: PWZER/swagger-ui-py
• PyPI: swagger-ui-py