111 lines
2.2 KiB
Python
111 lines
2.2 KiB
Python
"""
|
|
# 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:
|
|
|
|
```bash
|
|
pip install openapi-first
|
|
```
|
|
|
|
Or with Poetry:
|
|
|
|
```bash
|
|
poetry add openapi-first
|
|
```
|
|
|
|
---
|
|
|
|
# Quick Start
|
|
|
|
Minimal OpenAPI-first FastAPI application:
|
|
|
|
```python
|
|
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:
|
|
|
|
```python
|
|
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",
|
|
]
|