Skip to main content

fastapi-openapi-plus

Library for simplifying OpenAPI documentation in FastAPI (parameters, schemas, examples).

Repository: github.com/seligoroff/fastapi-openapi-plus

Overview

fastapi-openapi-plus helps reduce boilerplate when documenting FastAPI endpoints by providing:

  • Helper functions for parameters (query_param, path_param, body_param)
  • Typed helpers for common types (query_uuid, path_uuid, query_bool, query_int)
  • Automatic example generation via registry pattern (ExampleGenerators)
  • Pydantic v1/v2 compatibility for field documentation (field, add_example_to_model)
  • Validation tools for checking documentation completeness (validate_on_startup, audit CLI)

Works seamlessly with fastapi-errors-plus for complete OpenAPI documentation coverage.

Installation

pip install fastapi-openapi-plus

For CLI audit functionality:

pip install fastapi-openapi-plus[audit]

Quick Start

from fastapi import APIRouter
from fastapi_openapi_plus import query_uuid, path_uuid, query_bool, query_int

router = APIRouter()

@router.get("/players/{playerId}/statistic")
async def get_statistic(
    player_id: str = path_uuid(description="Уникальный идентификатор игрока"),
    season_id: str = query_uuid(alias="seasonId", description="ID сезона для фильтрации"),
    include_stats: bool = query_bool(alias="includeStats", description="Включить статистику", default=False),
    page: int = query_int(alias="page", description="Номер страницы", default=1, ge=1),
):
    return {"player_id": player_id, "season_id": season_id}

Result in Swagger UI:

  • ✅ All parameters have descriptions
  • ✅ All parameters have realistic examples (auto-generated UUIDs, etc.)
  • ✅ Validation constraints (ge=1) are applied

Using basic parameter helpers

from fastapi import APIRouter
from fastapi_openapi_plus import query_param, path_param, body_param

router = APIRouter()

@router.get("/items/{item_id}")
async def get_item(
    item_id: int = path_param(
        description="Уникальный идентификатор элемента",
        type_hint=int,
    ),
    page: int = query_param(
        description="Номер страницы",
        alias="page",
        default=1,
        type_hint=int,
    ),
):
    return {"item_id": item_id, "page": page}

@router.post("/items")
async def create_item(
    item: dict = body_param(
        description="Данные элемента для создания",
        type_hint=dict,
    ),
):
    return {"item": item}

Using Pydantic field helpers

from pydantic import BaseModel
from fastapi_openapi_plus import field

class UserModel(BaseModel):
    name: str = field(description="Имя пользователя", type_hint=str)
    age: int = field(description="Возраст", type_hint=int, ge=0, le=120)
    email: str = field(description="Email", example="user@example.com")

Using automatic model examples

from pydantic import BaseModel
from fastapi_openapi_plus import add_example_to_model

class UserModel(BaseModel):
    name: str
    age: int

# Автоматически генерирует примеры для всех полей
add_example_to_model(UserModel)

# Теперь в OpenAPI будет пример:
# {"name": "example_string", "age": 1}

Using custom generators

from fastapi_openapi_plus import ExampleGenerators
from uuid import uuid4

# Register custom type generator
class CustomType:
    pass

ExampleGenerators.register(CustomType, lambda: "custom_example")

# Now it works automatically
from fastapi_openapi_plus import query_param

custom_param = query_param(
    description="Custom parameter",
    type_hint=CustomType,
)  # example will be "custom_example"

Validating documentation on startup

from fastapi import FastAPI
from fastapi_openapi_plus.validators import validate_on_startup

app = FastAPI()

# ... define your routes ...

# Validate documentation at startup (outputs warnings, doesn't break app)
validate_on_startup(app)

Using CLI audit

# Check documentation via app import
python -m fastapi_openapi_plus audit "myapp.main:app"

# Check documentation via OpenAPI URL
python -m fastapi_openapi_plus audit --openapi-url http://localhost:8000/openapi.json

# Save report to file
python -m fastapi_openapi_plus audit "myapp.main:app" -o report.json

API Reference

Parameter Helpers

query_param(description, default=..., alias=None, type_hint=None, examples=None, **kwargs)

Helper for query parameters with automatic example generation.

Parameters:

  • description (str, required): Parameter description (cannot be empty)
  • default (Any, optional): Default value. If not ..., used as example
  • alias (str, optional): Alternative parameter name in request
  • type_hint (type, optional): Type for auto-generating example
  • examples (List[Dict], optional): Explicit examples (has priority over auto-generation)
  • **kwargs: Additional parameters for Query() (ge, le, min_length, etc.)

Returns: Query object with description and examples

Example:

page: int = query_param(
    description="Номер страницы",
    type_hint=int,
)  # examples will be [{"value": 1}]

path_param(description, type_hint=None, examples=None, **kwargs)

Helper for path parameters with automatic example generation.

Parameters:

  • description (str, required): Parameter description (cannot be empty)
  • type_hint (type, optional): Type for auto-generating example
  • examples (List[Dict], optional): Explicit examples (has priority over auto-generation)
  • **kwargs: Additional parameters for Path() (ge, le, min_length, etc.)

Returns: Path object with description and examples

Note: Path parameters do not accept alias (name is taken from route template).

Example:

item_id: int = path_param(
    description="Уникальный идентификатор элемента",
    type_hint=int,
)

body_param(description, embed=False, examples=None, default=..., type_hint=None, **kwargs)

Helper for body parameters with automatic example generation.

Parameters:

  • description (str, required): Parameter description (cannot be empty)
  • embed (bool, optional): Embed body in schema (default: False)
  • examples (List[Dict], optional): Explicit examples (has priority over auto-generation)
  • default (Any, optional): Default value. If not ..., used as example
  • type_hint (type, optional): Type for auto-generating example
  • **kwargs: Additional parameters for Body() (media_type, etc.)

Returns: Body object with description and examples

Example:

item: dict = body_param(
    description="Данные элемента для создания",
    type_hint=dict,
)

Typed Helpers

query_uuid(description, alias=None, default=..., **kwargs)

Query parameter for UUID with automatic UUID generation.

Example:

season_id: str = query_uuid(
    alias="seasonId",
    description="ID сезона для фильтрации",
)

path_uuid(description, **kwargs)

Path parameter for UUID with automatic UUID generation.

Note: Does not accept alias parameter.

Example:

player_id: str = path_uuid(description="Уникальный идентификатор игрока")

query_bool(description, alias=None, default=False, **kwargs)

Query parameter for boolean with default used as example.

Example:

include_stats: bool = query_bool(
    alias="includeStats",
    description="Включить статистику",
    default=False,
)

query_int(description, alias=None, default=..., ge=None, le=None, **kwargs)

Query parameter for integer with example generation considering constraints.

Example:

page: int = query_int(
    alias="page",
    description="Номер страницы",
    default=1,
    ge=1,
)

Example Generators

ExampleGenerators

Registry for type-to-generator mappings.

Methods:

  • register(type_hint, generator): Register a generator for a type
  • generate_for_type(type_hint): Generate example for a type (returns None if not found)
  • reset(): Reset registry to default generators
  • unregister(type_hint): Remove generator for a type

Pre-registered types: str, int, bool, float, UUID, datetime

Example:

from fastapi_openapi_plus import ExampleGenerators

# Register custom generator
ExampleGenerators.register(MyType, lambda: MyType.example())

# Generate example
example = ExampleGenerators.generate_for_type(MyType)  # Returns MyType.example()

Pydantic Integration

field(description, *, default=..., alias=None, type_hint=None, example=None, **kwargs)

Helper for Pydantic Field with automatic example generation and v1/v2 support.

Parameters:

  • description (str, required): Field description (cannot be empty)
  • default (Any, optional): Default value. If not ..., used as example
  • alias (str, optional): Alternative field name in JSON
  • type_hint (type, optional): Type for auto-generating example
  • example (Any, optional): Explicit example (has priority over auto-generation)
  • **kwargs: Additional parameters for Field() (ge, le, min_length, etc.)

Returns: Pydantic Field object with description and example

Example:

from pydantic import BaseModel
from fastapi_openapi_plus import field

class UserModel(BaseModel):
    name: str = field(description="Имя пользователя", type_hint=str)
    age: int = field(description="Возраст", type_hint=int, ge=0, le=120)

add_example_to_model(model)

Adds automatically generated examples to a Pydantic model.

Parameters:

  • model (Type[BaseModel]): Pydantic model class

Returns: The same model class with added examples

Note: For Pydantic v2, automatically calls model.model_rebuild() after configuration changes.

Example:

from pydantic import BaseModel
from fastapi_openapi_plus import add_example_to_model

class UserModel(BaseModel):
    name: str
    age: int

add_example_to_model(UserModel)
# Now OpenAPI will include example: {"name": "example_string", "age": 1}

Validation Tools

validate_on_startup(app)

Validates OpenAPI documentation completeness at application startup.

Parameters:

  • app (FastAPI): FastAPI application

Behavior:

  • Checks for missing description and example in parameters and request body
  • Outputs warnings.warn() for issues (does not raise exceptions)
  • Does not break application startup

Example:

from fastapi import FastAPI
from fastapi_openapi_plus.validators import validate_on_startup

app = FastAPI()

# ... define routes ...

validate_on_startup(app)

CLI: audit

Command-line tool for auditing OpenAPI documentation.

Usage:

# Via app import
python -m fastapi_openapi_plus audit "myapp.main:app"

# Via OpenAPI URL
python -m fastapi_openapi_plus audit --openapi-url http://localhost:8000/openapi.json

# Save report
python -m fastapi_openapi_plus audit "myapp.main:app" -o report.json

Exit codes:

  • 0: No issues found
  • 1: Issues found

How Auto-Generation Works

Auto-generation of examples works only if:

  1. ✅ Explicit examples parameter is provided — always works
  2. ✅ Typed helper is used (query_uuid, path_uuid, query_bool, query_int) — always works
  3. ✅ type_hint is provided and a generator is registered for the type — works after registration
  4. ❌ Otherwise — example is not generated (remains None)

Important: The library does not substitute placeholder data if a generator is not found.

Features

  • ✅ Transparent API: Simple wrappers over FastAPI/Pydantic functions
  • ✅ Explicit parameters: All parameters must be explicitly specified (description is required)
  • ✅ Pydantic v1/v2 compatibility: Automatic version detection
  • ✅ Type normalization: Handles Optional[T], Union[T, None], Annotated[T, ...]
  • ✅ Test isolation: ExampleGenerators.reset() and unregister() for clean tests
  • ✅ Validation tools: Startup validation and CLI audit

Requirements

  • Python >= 3.8
  • FastAPI >= 0.104.0
  • Pydantic >= 1.10.0

Development

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

# Run tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=fastapi_openapi_plus --cov-report=term-missing

# Run linter
ruff check .

# Run type checker
mypy fastapi_openapi_plus/

License

MIT

Metadata

Release files for fastapi-openapi-plus 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fastapi-openapi-plus 0.1.0
File Size Uploaded Provenance Actions
fastapi_openapi_plus-0.1.0.tar.gz 38.5 kB Without provenance Details for fastapi_openapi_plus-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for fastapi-openapi-plus 0.1.0
File Interpreter ABI Platform Actions
fastapi_openapi_plus-0.1.0-py3-none-any.whl Python 3 none any Details for fastapi_openapi_plus-0.1.0-py3-none-any.whl

Total release size: 65.3 kB

Release files / fastapi_openapi_plus-0.1.0.tar.gz

Download URL fastapi_openapi_plus-0.1.0.tar.gz
Size 38.5 kB
Tags Source
SHA-256 checksum
How to use checksums
53259960a7f7f26b4e4a5f4f3cef6cb709197394a629b6d2e03f94b1733d234d
BLAKE2b-256 checksum
How to use checksums
72593a9eb43aef1b45ac01c9ce6c0b2fa522a7b3759b93bef785f2337d6913a3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.11.2

Release files / fastapi_openapi_plus-0.1.0-py3-none-any.whl

Download URL fastapi_openapi_plus-0.1.0-py3-none-any.whl
Size 26.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2ccdd6db461b8dbe6ad009f0f48c23cc333fb56ff897d2e905bd9acb05296cdd
BLAKE2b-256 checksum
How to use checksums
7a3489ee87b0be904f7d0084a34efe368bd0a79c35eb04730a21eb3edd58c03c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.11.2

Security for fastapi-openapi-plus 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page