Skip to content

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:

1
2
3
4
5
6
- 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:

1
2
3
4
- 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:

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

Classes

OpenAPIFirstApp 

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

Bases: FastAPI

FastAPI application enforcing OpenAPI-first design.

Notes

Responsibilities:

1
2
3
4
5
- `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.

Guarantees:

1
2
3
4
- 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.
Example 
1
2
3
4
5
6
7
8
from openapi_first import OpenAPIFirstApp
import app.routes as routes

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

Initialize the application.

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 module

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.
Functions

Functions