Skip to content

Openapi First

openapi_first

FastAPI OpenAPI First — strict OpenAPI-first application bootstrap for FastAPI.

FastAPI OpenAPI First is a contract-first infrastructure library that enforces OpenAPI as the single source of truth for FastAPI services.

The library removes decorator-driven routing and replaces it with deterministic, spec-driven application assembly. Every HTTP route, method, and operation is defined in OpenAPI first and bound to Python handlers explicitly via operationId.

The package is intentionally minimal and layered. Each module has a single responsibility and exposes explicit contracts rather than convenience facades.

Architecture Overview

The library is structured around four core responsibilities:

  • loader: load and validate OpenAPI 3.x specifications (JSON/YAML)
  • binder: bind OpenAPI operations to FastAPI routes via operationId
  • app: OpenAPI-first FastAPI application bootstrap
  • client: OpenAPI-first HTTP client driven by the same specification
  • errors: explicit error hierarchy for contract violations

The package root acts as a namespace, not a facade. Consumers are expected to import functionality explicitly from the appropriate module.

Installation

Install using pip:

pip install openapi-first

Or with Poetry:

poetry add openapi-first

Runtime dependencies are intentionally minimal: - fastapi (server-side) - httpx (client-side) - openapi-spec-validator - pyyaml (optional, for YAML specs)

The ASGI server (e.g., uvicorn) is an application-level dependency and is not bundled with this library.

Command-Line Interface (Scaffolding, Templates)

FastAPI OpenAPI First ships with a small CLI for bootstrapping OpenAPI-first FastAPI applications from bundled templates.

List available application templates:

openapi-first --list

Create a new application using the default template:

openapi-first

Create a new application using a specific template:

openapi-first health_app

Create a new application in a custom directory:

openapi-first health_app my-service

The CLI copies template files verbatim into the target directory. No code is generated or modified beyond the copied scaffold.

Server-Side Usage (OpenAPI → FastAPI)

Minimal OpenAPI-first FastAPI application:

from openapi_first import app
import my_service.routes as routes

api = app.OpenAPIFirstApp(
    openapi_path="openapi.yaml",
    routes_module=routes,
    title="My Service",
    version="1.0.0",
)

# Run with:
# uvicorn my_service.main:api

Handler definitions (no decorators):

def get_health():
    return {"status": "ok"}

OpenAPI snippet:

paths:
  /health:
    get:
      operationId: get_health
      responses:
        "200":
          description: OK

The binder guarantees: - Every OpenAPI operationId has exactly one handler - No undocumented routes exist - All mismatches fail at application startup

Client-Side Usage (OpenAPI → HTTP Client)

The same OpenAPI specification can be used to construct a strict, operationId-driven HTTP client.

Client construction:

from openapi_first.loader import load_openapi
from openapi_first.client import OpenAPIClient

spec = load_openapi("openapi.yaml")

client = OpenAPIClient(spec)

Calling operations (operationId is the API):

response = client.get_health()
assert response.status_code == 200
assert response.json() == {"status": "ok"}

Path parameters must match the OpenAPI specification exactly:

response = client.get_item(
    path_params={"item_id": 1}
)

Request bodies are passed explicitly:

response = client.create_item(
    body={"name": "Orange", "price": 0.8}
)

Client guarantees: - One callable per OpenAPI operationId - No hardcoded URLs or HTTP methods in user code - Path and body parameters must match the spec exactly - Invalid or incomplete OpenAPI specs fail at client construction time - No schema inference or mutation is performed

The client is transport-level only and returns httpx.Response objects directly. Response interpretation and validation are left to the consumer or higher-level layers.

Extensibility Model

FastAPI OpenAPI First is designed to be extended via explicit contracts:

  • Users MAY extend OpenAPI loading behavior (e.g. multi-file specs) by wrapping or replacing loader.load_openapi
  • Users MAY extend route binding behavior by building on top of binder.bind_routes
  • Users MAY layer additional validation (e.g. signature checks) without modifying core modules

Users SHOULD NOT rely on FastAPI decorators for routing when using this library. Mixing decorator-driven routes with OpenAPI-first routing defeats the contract guarantees and is explicitly unsupported.

Public API Surface

The supported public API consists of the following top-level modules:

  • openapi_first.app
  • openapi_first.binder
  • openapi_first.loader
  • openapi_first.client
  • openapi_first.errors

Classes and functions should be imported explicitly from these modules. No individual symbols are re-exported at the package root.

Design Guarantees

  • OpenAPI is the single source of truth
  • No undocumented routes can exist
  • No OpenAPI operation can exist without a handler or client callable
  • All contract violations fail at application startup or client creation
  • No hidden FastAPI magic or implicit behavior
  • Deterministic, testable application assembly
  • CI-friendly failure modes

FastAPI OpenAPI First favors correctness, explicitness, and contract enforcement over convenience shortcuts.

Core Philosophy

FastAPI OpenAPI First operates on the Contract-as-Code principle:

  1. Spec-Driven Routing: The OpenAPI document is the router. Code only exists to fulfill established contracts.
  2. Startup Fail-Fast: Binding mismatches (missing handlers or extra operations) are detected during app initialization, not at runtime.
  3. Decoupled Symmetry: The same specification drives both the FastAPI server and the httpx-based client, ensuring type-safe communication.

Documentation Design

Follow these "AI-Native" docstring principles to maximize developer and agent productivity:

For Humans
  • Logical Grouping: Document the Loader, Binder, and Client as distinct infrastructure layers.
  • Spec Snippets: Always include the corresponding OpenAPI YAML/JSON snippet alongside Python examples.
For LLMs
  • Full Path Linking: Refer to cross-module dependencies using their full dotted paths (e.g., openapi_first.loader.load_openapi).
  • Complete Stubs: Maintain high-fidelity .pyi stubs for all public interfaces to provide an optimized machine-context.
  • Traceable Errors: Use specific : description pairs in Raises blocks to allow agents to accurately map errors to spec violations.