105 lines
2.3 KiB
Python
105 lines
2.3 KiB
Python
"""
|
|
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:
|
|
|
|
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
|
|
|
|
---
|
|
"""
|
|
|
|
from . import app
|
|
from . import binder
|
|
from . import loader
|
|
from . import client
|
|
from . import errors
|
|
|
|
__all__ = [
|
|
"app",
|
|
"binder",
|
|
"loader",
|
|
"client",
|
|
"errors",
|
|
]
|