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