App

openapi_first.app

Summary

OpenAPI-first application bootstrap for FastAPI.

This module provides OpenAPIFirstApp, a thin but strict abstraction that enforces OpenAPI as the single source of truth for a FastAPI service.

Notes

Core Principles:

- The OpenAPI specification (JSON or YAML) defines the entire API surface.
- Every `operationId` in the OpenAPI spec must have a corresponding
  Python handler function.
- Handlers are plain Python callables (no FastAPI decorators).
- FastAPI route registration is derived exclusively from the spec.
- FastAPI's autogenerated OpenAPI schema is fully overridden.

Responsibilities:

- Loads and validates an OpenAPI 3.x specification.
- Dynamically binds HTTP routes to handler functions using `operationId`.
- Registers routes with FastAPI at application startup.
- Ensures runtime behavior matches the OpenAPI contract exactly.

Constraints:

- This module intentionally does NOT:
    - Generate OpenAPI specs.
    - Generate client code.
    - Introduce a new framework or lifecycle.
    - Alter FastAPI dependency injection semantics.

Classes

OpenAPIFirstApp

OpenAPIFirstApp(
    *,
    openapi_path: str,
    routes_module: Any,
    **fastapi_kwargs: Any
)

Bases: FastAPI

FastAPI application enforcing OpenAPI-first design.

Parameters:

Name	Type	Description	Default
openapi_path	str	Filesystem path to the OpenAPI 3.x specification file. This specification is treated as the authoritative API contract.	required
routes_module	ModuleType	Python module containing handler functions whose names correspond exactly to OpenAPI operationId values.	required
**fastapi_kwargs	Any	Additional keyword arguments passed directly to fastapi.FastAPI (e.g., title, version, middleware, lifespan handlers).	{}

Raises:

Type	Description
OpenAPIFirstError	If the OpenAPI specification is invalid, or if any declared operationId does not have a corresponding handler function.

Notes

Responsibilities:

- `OpenAPIFirstApp` subclasses `FastAPI` and replaces manual route
  registration with OpenAPI-driven binding.
- All routes are derived from the provided OpenAPI specification,
  and each ``operationId`` is mapped to a Python function in the
  supplied routes module.
- Auth dependencies are auto-injected from the spec's
  ``securitySchemes`` and per-operation ``security`` fields.

Guarantees:

- No route can exist without an OpenAPI declaration.
- No OpenAPI operation can exist without a handler.
- Swagger UI and ``/openapi.json`` always reflect the provided spec.
- Handler functions remain framework-agnostic and testable.
- Auth enforcement is driven entirely by the spec — no manual
  middleware or decorators required.

Example

from openapi_first.app import OpenAPIFirstApp
import app.routes as routes

app = OpenAPIFirstApp(
    openapi_path="app/openapi.json",
    routes_module=routes,
    title="Example Service",
)

Functions