Skip to content

App

openapi_first.app

openapi_first.app

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.

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.

What this module does

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

What this module does NOT do

  • It does not generate OpenAPI specs.
  • It does not generate client code.
  • It does not introduce a new framework or lifecycle.
  • It does not alter FastAPI dependency injection semantics.

Intended usage

This module is intended for teams that want:

  • OpenAPI-first API development
  • Strong contract enforcement
  • Minimal FastAPI boilerplate
  • Predictable, CI-friendly failures for spec/implementation drift

OpenAPIFirstApp 

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

Bases: FastAPI

FastAPI application enforcing OpenAPI-first design.

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.

Parameters

openapi_path : str Filesystem path to the OpenAPI 3.x specification file. This specification is treated as the authoritative API contract.

module

Python module containing handler functions whose names correspond exactly to OpenAPI operationId values.

**fastapi_kwargs Additional keyword arguments passed directly to fastapi.FastAPI (e.g., title, version, middleware, lifespan handlers).

Raises

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

Behavior 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" ... )