Skip to content

Openapi First

openapi_first

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

Summary

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.

Installation

Install using pip:

1
pip install openapi-first

Or with Poetry:

1
poetry add openapi-first

Quick start

Minimal OpenAPI-first FastAPI application:

1
2
3
4
5
6
7
8
9
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",
)

OperationId-driven HTTP client:

1
2
3
4
5
6
7
from openapi_first.loader import load_openapi
from openapi_first.client import OpenAPIClient

spec = load_openapi("openapi.yaml")
client = OpenAPIClient(spec)

response = client.get_health()

Architecture

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

Public API

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

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