aiohttp-swagger-utils

A utility package for integrating Swagger/OpenAPI UI into aiohttp applications. Simplifies setup, adds middleware for basic request validation, and supports both Swagger UI and ReDoc.

Features

• 🚀 Easy Integration: Simple setup with minimal configuration
• 📋 Swagger UI Support: Automatic Swagger UI endpoint generation
• 📖 ReDoc Support: Alternative API documentation viewer
• ✅ Request Validation: Middleware for basic OpenAPI schema validation
• 📄 Multiple Spec Formats: Support for YAML and JSON OpenAPI specifications
• 🔧 Flexible Configuration: Customizable UI options and validation settings
• 🧪 Type Hints: Full type annotations for better IDE support
• 📚 Well Documented: Comprehensive documentation and examples

Installation

Install via pip:

pip install aiohttp-swagger-utils

Quick Start

Basic Usage

from aiohttp import web
from aiohttp_swagger_utils import setup_swagger_ui, setup_redoc

app = web.Application()

# Load your OpenAPI specification
spec_path = "openapi.yaml"

# Setup Swagger UI
setup_swagger_ui(app, spec_path=spec_path, url_prefix="/api/docs")

# Setup ReDoc (optional)
setup_redoc(app, spec_path=spec_path, url_prefix="/api/redoc")

# Your routes
async def hello(request):
    return web.json_response({"message": "Hello World"})

app.router.add_get("/", hello)

web.run_app(app)

With Request Validation

from aiohttp import web
from aiohttp_swagger_utils import setup_swagger_ui, SwaggerValidationMiddleware

app = web.Application()

# Add validation middleware
app.middlewares.append(SwaggerValidationMiddleware("openapi.yaml").middleware)

# Setup Swagger UI
setup_swagger_ui(app, spec_path="openapi.yaml")

async def create_user(request):
    # Request will be validated against OpenAPI spec
    data = await request.json()
    return web.json_response({"status": "created", "data": data})

app.router.add_post("/users", create_user)

web.run_app(app)

Configuration Options

setup_swagger_ui()

setup_swagger_ui(
    app: web.Application,
    spec_path: str,
    url_prefix: str = "/api/docs",
    title: str = "API Documentation",
    enable_validator: bool = True,
    oauth2_redirect_url: Optional[str] = None,
    custom_css_url: Optional[str] = None,
    custom_js_url: Optional[str] = None
)

setup_redoc()

setup_redoc(
    app: web.Application,
    spec_path: str,
    url_prefix: str = "/api/redoc",
    title: str = "API Documentation",
    expand_responses: str = "200,201",
    required_props_first: bool = True
)

SwaggerValidationMiddleware

middleware = SwaggerValidationMiddleware(
    spec_path: str,
    validate_request: bool = True,
    validate_response: bool = False,
    raise_on_error: bool = True
)

Advanced Example

from aiohttp import web
from aiohttp_swagger_utils import (
    setup_swagger_ui,
    setup_redoc,
    SwaggerValidationMiddleware
)

async def init_app():
    app = web.Application()
    
    # Load OpenAPI spec
    spec_path = "openapi.yaml"
    
    # Add validation middleware
    validation_middleware = SwaggerValidationMiddleware(
        spec_path=spec_path,
        validate_request=True,
        validate_response=False,
        raise_on_error=True
    )
    app.middlewares.append(validation_middleware.middleware)
    
    # Setup Swagger UI
    setup_swagger_ui(
        app=app,
        spec_path=spec_path,
        url_prefix="/docs",
        title="My Awesome API",
        enable_validator=True,
        custom_css_url="/static/custom-swagger.css"
    )
    
    # Setup ReDoc as alternative
    setup_redoc(
        app=app,
        spec_path=spec_path,
        url_prefix="/redoc",
        title="My Awesome API - ReDoc",
        expand_responses="200,201,204",
        required_props_first=True
    )
    
    # Add routes
    app.router.add_get("/", lambda r: web.json_response({"status": "ok"}))
    app.router.add_post("/items", create_item)
    
    return app

if __name__ == "__main__":
    web.run_app(init_app(), port=8080)

Testing

Run tests with pytest:

pytest tests/

Or with unittest:

python -m unittest discover tests