aiohttp-swagger-utils 0.1.0
Swagger/OpenAPI UI integration utilities for aiohttp applications
License: MIT
Requires Python: >=3.8

# aiohttp-swagger-utils

[![PyPI version](https://badge.fury.io/py/aiohttp-swagger-utils.svg)](https://badge.fury.io/py/aiohttp-swagger-utils)
[![PyPI downloads](https://img.shields.io/pypi/dm/aiohttp-swagger-utils.svg)](https://pypi.org/project/aiohttp-swagger-utils/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Versions](https://img.shields.io/pypi/pyversions/aiohttp-swagger-utils.svg)](https://pypi.org/project/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:

```bash
pip install aiohttp-swagger-utils
```

## Quick Start
### Basic Usage
```python
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
```python
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()
```python
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()
```python
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
```python
middleware = SwaggerValidationMiddleware(
    spec_path: str,
    validate_request: bool = True,
    validate_response: bool = False,
    raise_on_error: bool = True
)
```
## Advanced Example
```python
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:
```bash
pytest tests/
```
Or with unittest:
```bash
python -m unittest discover tests
```