Skip to content

# 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:

    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.