openapi_first

openapi_first

Summary

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.

---

Installation

Install using pip:

pip install openapi-first

Or with Poetry:

poetry add openapi-first

---

Quick Start

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",
)

OperationId-driven HTTP client:

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.

---