App

openapi_first.app

OpenAPI-first application bootstrap for FastAPI.

---

Summary

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, or 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.

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

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

Example

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