FastOpenAPI

FastOpenAPI is a library designed to bring a FastAPI-style developer experience to various Python web frameworks. It enables automatic OpenAPI schema generation, interactive documentation (Swagger UI and ReDoc), request validation via Pydantic, and response serialization, all while remaining framework-agnostic.

Key capabilities include:

• Automatic OpenAPI generation: Derived from your route definitions.
• Interactive Docs: Access via Swagger UI or ReDoc.
• Pydantic v2 Integration: For robust validation and JSON Schema generation.
• Multi-Framework Support: Works with AIOHTTP, Django, Falcon, Flask, Quart, Sanic, Starlette, and Tornado.

FastOpenAPI provides specialized router classes for various web frameworks. Choose the router that matches your framework and whether you are using synchronous or asynchronous patterns:

• aiohttp: AioHttpRouter (async)
• Django: DjangoRouter (sync) or DjangoAsyncRouter (async)
• Falcon: FalconRouter (sync) or FalconAsyncRouter (async)
• Flask: FlaskRouter (sync)
• Quart: QuartRouter (async)
• Sanic: SanicRouter (async)
• Starlette: StarletteRouter (async)
• Tornado: TornadoRouter (async/sync)
• Generic/Other: StarletteRouter is often used for general ASGI-compatible apps.

FastOpenAPI is a library designed to add OpenAPI/Swagger documentation and request/response validation to existing web frameworks.

Key distinction from FastAPI:

• FastAPI is a full web framework with native OpenAPI integration.
• FastOpenAPI is a library you add to existing frameworks (like Flask, AIOHTTP, etc.) to provide similar developer experiences without switching frameworks.

When to use FastOpenAPI:

• You have an existing application in another framework.
• You need to support multiple different frameworks with a single toolset.

FastOpenAPI leverages Pydantic for three core tasks:

1. Request Body Validation: Ensuring incoming data matches the expected schema.
2. Response Serialization: Converting Python objects/dicts into JSON.
3. Schema Generation: Automatically creating JSON Schemas for the OpenAPI document.

When using response_model in a decorator, FastOpenAPI validates the return value of your function against that model. If the response is invalid, it raises an InternalServerError (500).

from pydantic import BaseModel, Field

class Item(BaseModel):
    name: str = Field(..., description="Item name")
    price: float = Field(..., gt=0, description="Price must be positive")
    description: str | None = None

@router.post("/items", response_model=Item)
def create_item(item: Item = Body(...)):
    # item is already validated
    return item

Routes are matched in the order they are defined. Always define more specific routes (e.g., /items/featured) before generic routes with path parameters (e.g., /items/{item_id}) to prevent the generic route from intercepting requests intended for the specific one.

# Correct order
@router.get("/items/featured")
def get_featured():
    return {"items": ["featured1"]}

@router.get("/items/{item_id}")
def get_item(item_id: int):
    return {"item_id": item_id}

FastOpenAPI acts as a bridge between your existing web framework (like Flask or Django) and OpenAPI documentation. It registers routes with your framework, validates incoming requests against Pydantic models, generates the OpenAPI schema, and provides interactive documentation via Swagger UI or ReDoc.

The Request Flow:

1. Route Definition: You define routes using FastOpenAPI decorators.
2. Registration: FastOpenAPI registers these routes with your underlying framework.
3. Request Handling: When a request arrives, FastOpenAPI extracts parameters, validates them against Pydantic models, calls your endpoint, and then validates/serializes the response.
4. Schema Generation: The OpenAPI schema is generated from your route definitions.
5. Documentation: Documentation UIs (Swagger UI, ReDoc) consume the schema to create interactive docs.

FastOpenAPI parameters extend Pydantic's FieldInfo. You can use them to define where parameters are located (Query, Path, Header, Cookie, Body) and apply validation constraints.

Parameter Hierarchy:

• BaseParam (extends FieldInfo)
  • Param (adds in_ source)
    • Query (in_ = QUERY)
    • Path (in_ = PATH)
    • Header (in_ = HEADER, supports convert_underscores)
    • Cookie (in_ = COOKIE)
  • Body (adds body-specific logic)
    • Form (in_ = FORM)
    • File (in_ = FILE)

Pydantic allows for complex, deeply nested data structures by using other BaseModel classes as type hints.

from pydantic import BaseModel, EmailStr
from datetime import datetime

class Address(BaseModel):
    street: str
    city: str
    postal_code: str
    country: str = "USA"

class User(BaseModel):
    name: str
    email: EmailStr
    address: Address  # Nested model

class Order(BaseModel):
    order_id: int
    items: list[Address]  # List of nested models

FastOpenAPI includes a FastAPI-like dependency injection (DI) system. It supports:

• Depends(func): For regular dependencies.
• Security(func, scopes=[...]): For security-related dependencies.
• SecurityScopes: For injecting scopes.

DI Features:

• Recursive resolution.
• Request-scoped caching.
• Circular dependency detection.
• Async dependencies.
• Generator (yield) dependencies with automatic cleanup.

Note: FastOpenAPI does not provide background tasks or middleware injection; you should use your underlying web framework's native mechanisms for those features.

When analyzing the benchmark results, use the following mental model to understand the performance impact of different layers:

• Pure Performance: Represents the raw framework overhead (routing, parsing, serialization). This is the 100% baseline.
• Validators Overhead: The cost of adding Pydantic validation for both input (request) and output (response) models. Typically adds 5-15% overhead.
• FastOpenAPI Overhead: The cost of adding automatic OpenAPI documentation generation (router proxy layer, schema extraction, etc.). Typically adds 8-20% overhead on top of the Pure implementation.
• FastAPI Comparison: Used to determine if FastOpenAPI is competitive with the industry standard for async frameworks with built-in validation and docs.