google styled doc
This commit is contained in:
@@ -1,6 +1,10 @@
|
||||
"""
|
||||
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.
|
||||
|
||||
@@ -9,28 +13,9 @@ deterministic, spec-driven application assembly. Every HTTP route,
|
||||
method, and operation is defined in OpenAPI first and bound to Python
|
||||
handlers explicitly via operationId.
|
||||
|
||||
The package is intentionally minimal and layered. Each module has a
|
||||
single responsibility and exposes explicit contracts rather than
|
||||
convenience facades.
|
||||
---
|
||||
|
||||
----------------------------------------------------------------------
|
||||
Architecture Overview
|
||||
----------------------------------------------------------------------
|
||||
|
||||
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
|
||||
|
||||
The package root acts as a **namespace**, not a facade. Consumers are
|
||||
expected to import functionality explicitly from the appropriate module.
|
||||
|
||||
----------------------------------------------------------------------
|
||||
Installation
|
||||
----------------------------------------------------------------------
|
||||
## Installation
|
||||
|
||||
Install using pip:
|
||||
|
||||
@@ -40,44 +25,9 @@ Or with Poetry:
|
||||
|
||||
poetry add openapi-first
|
||||
|
||||
Runtime dependencies are intentionally minimal:
|
||||
- fastapi (server-side)
|
||||
- httpx (client-side)
|
||||
- openapi-spec-validator
|
||||
- pyyaml (optional, for YAML specs)
|
||||
---
|
||||
|
||||
The ASGI server (e.g., uvicorn) is an application-level dependency and is
|
||||
not bundled with this library.
|
||||
|
||||
----------------------------------------------------------------------
|
||||
Command-Line Interface (Scaffolding, Templates)
|
||||
----------------------------------------------------------------------
|
||||
|
||||
FastAPI OpenAPI First ships with a small CLI for bootstrapping
|
||||
OpenAPI-first FastAPI applications from bundled templates.
|
||||
|
||||
List available application templates:
|
||||
|
||||
openapi-first --list
|
||||
|
||||
Create a new application using the default template:
|
||||
|
||||
openapi-first
|
||||
|
||||
Create a new application using a specific template:
|
||||
|
||||
openapi-first health_app
|
||||
|
||||
Create a new application in a custom directory:
|
||||
|
||||
openapi-first health_app my-service
|
||||
|
||||
The CLI copies template files verbatim into the target directory.
|
||||
No code is generated or modified beyond the copied scaffold.
|
||||
|
||||
----------------------------------------------------------------------
|
||||
Server-Side Usage (OpenAPI → FastAPI)
|
||||
----------------------------------------------------------------------
|
||||
## Quick start
|
||||
|
||||
Minimal OpenAPI-first FastAPI application:
|
||||
|
||||
@@ -91,109 +41,43 @@ Minimal OpenAPI-first FastAPI application:
|
||||
version="1.0.0",
|
||||
)
|
||||
|
||||
# Run with:
|
||||
# uvicorn my_service.main:api
|
||||
|
||||
Handler definitions (no decorators):
|
||||
|
||||
def get_health():
|
||||
return {"status": "ok"}
|
||||
|
||||
OpenAPI snippet:
|
||||
|
||||
paths:
|
||||
/health:
|
||||
get:
|
||||
operationId: get_health
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
|
||||
The binder guarantees:
|
||||
- Every OpenAPI operationId has exactly one handler
|
||||
- No undocumented routes exist
|
||||
- All mismatches fail at application startup
|
||||
|
||||
----------------------------------------------------------------------
|
||||
Client-Side Usage (OpenAPI → HTTP Client)
|
||||
----------------------------------------------------------------------
|
||||
|
||||
The same OpenAPI specification can be used to construct a strict,
|
||||
operationId-driven HTTP client.
|
||||
|
||||
Client construction:
|
||||
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)
|
||||
|
||||
Calling operations (operationId is the API):
|
||||
|
||||
response = client.get_health()
|
||||
assert response.status_code == 200
|
||||
assert response.json() == {"status": "ok"}
|
||||
|
||||
Path parameters must match the OpenAPI specification exactly:
|
||||
---
|
||||
|
||||
response = client.get_item(
|
||||
path_params={"item_id": 1}
|
||||
)
|
||||
## Architecture
|
||||
|
||||
Request bodies are passed explicitly:
|
||||
The library is structured around four core responsibilities:
|
||||
|
||||
response = client.create_item(
|
||||
body={"name": "Orange", "price": 0.8}
|
||||
)
|
||||
- **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
|
||||
|
||||
Client guarantees:
|
||||
- One callable per OpenAPI operationId
|
||||
- No hardcoded URLs or HTTP methods in user code
|
||||
- Path and body parameters must match the spec exactly
|
||||
- Invalid or incomplete OpenAPI specs fail at client construction time
|
||||
- No schema inference or mutation is performed
|
||||
---
|
||||
|
||||
The client is transport-level only and returns `httpx.Response`
|
||||
objects directly. Response interpretation and validation are left to
|
||||
the consumer or higher-level layers.
|
||||
|
||||
----------------------------------------------------------------------
|
||||
Extensibility Model
|
||||
----------------------------------------------------------------------
|
||||
|
||||
FastAPI OpenAPI First is designed to be extended via **explicit contracts**:
|
||||
|
||||
- Users MAY extend OpenAPI loading behavior (e.g. multi-file specs)
|
||||
by wrapping or replacing `loader.load_openapi`
|
||||
- Users MAY extend route binding behavior by building on top of
|
||||
`binder.bind_routes`
|
||||
- Users MAY layer additional validation (e.g. signature checks)
|
||||
without modifying core modules
|
||||
|
||||
Users SHOULD NOT rely on FastAPI decorators for routing when using this
|
||||
library. Mixing decorator-driven routes with OpenAPI-first routing
|
||||
defeats the contract guarantees and is explicitly unsupported.
|
||||
|
||||
----------------------------------------------------------------------
|
||||
Public API Surface
|
||||
----------------------------------------------------------------------
|
||||
## 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
|
||||
- `openapi_first.app`
|
||||
- `openapi_first.binder`
|
||||
- `openapi_first.loader`
|
||||
- `openapi_first.client`
|
||||
- `openapi_first.errors`
|
||||
|
||||
Classes and functions should be imported explicitly from these modules.
|
||||
No individual symbols are re-exported at the package root.
|
||||
---
|
||||
|
||||
----------------------------------------------------------------------
|
||||
Design Guarantees
|
||||
----------------------------------------------------------------------
|
||||
## Design Guarantees
|
||||
|
||||
- OpenAPI is the single source of truth
|
||||
- No undocumented routes can exist
|
||||
@@ -201,31 +85,8 @@ Design Guarantees
|
||||
- All contract violations fail at application startup or client creation
|
||||
- No hidden FastAPI magic or implicit behavior
|
||||
- Deterministic, testable application assembly
|
||||
- CI-friendly failure modes
|
||||
|
||||
FastAPI OpenAPI First favors correctness, explicitness, and contract
|
||||
enforcement over convenience shortcuts.
|
||||
|
||||
## Core Philosophy
|
||||
|
||||
`FastAPI OpenAPI First` operates on the **Contract-as-Code** principle:
|
||||
|
||||
1. **Spec-Driven Routing**: The OpenAPI document *is* the router. Code only exists to fulfill established contracts.
|
||||
2. **Startup Fail-Fast**: Binding mismatches (missing handlers or extra operations) are detected during app initialization, not at runtime.
|
||||
3. **Decoupled Symmetry**: The same specification drives both the FastAPI server and the `httpx`-based client, ensuring type-safe communication.
|
||||
|
||||
## Documentation Design
|
||||
|
||||
Follow these "AI-Native" docstring principles to maximize developer and agent productivity:
|
||||
|
||||
### For Humans
|
||||
- **Logical Grouping**: Document the Loader, Binder, and Client as distinct infrastructure layers.
|
||||
- **Spec Snippets**: Always include the corresponding OpenAPI YAML/JSON snippet alongside Python examples.
|
||||
|
||||
### For LLMs
|
||||
- **Full Path Linking**: Refer to cross-module dependencies using their full dotted paths (e.g., `openapi_first.loader.load_openapi`).
|
||||
- **Complete Stubs**: Maintain high-fidelity `.pyi` stubs for all public interfaces to provide an optimized machine-context.
|
||||
- **Traceable Errors**: Use specific `: description` pairs in `Raises` blocks to allow agents to accurately map errors to spec violations.
|
||||
---
|
||||
"""
|
||||
|
||||
from . import app
|
||||
|
||||
Reference in New Issue
Block a user