63 lines
3.3 KiB
Markdown
63 lines
3.3 KiB
Markdown
# 🧩 openapi-first — OpenAPI as the Single Source of Truth
|
||
|
||
`openapi-first` is a small, strict library for **OpenAPI-first FastAPI bootstrapping**: the OpenAPI document *is* the application contract — not an afterthought generated from decorators)Skip. Routes, schemas, security, and even the HTTP client are all derived from one specification.
|
||
|
||
> **Doc model:** this wiki is written for humans — how-to guides, examples, and usage recipes. The authoritative API contracts live in the code (docstrings) and the machine-readable bundle under `docs/mcp/`.
|
||
|
||
---
|
||
|
||
## 🚀 Key Features
|
||
|
||
* 📜 **One spec, two sides** — the same OpenAPI document boots both a FastAPI server (`OpenAPIFirstApp`) and a strict HTTP client (`OpenAPIClient`)
|
||
* 🔗 **`operationId` binding** — handler functions are bound to routes purely by `operationId`; no routing decorators
|
||
* 🧱 **Fail-fast contracts** — startup and client construction fail loudly when a handler, operation, or security scheme is missing
|
||
* 🛡️ **Spec-driven security** — `securitySchemes` + per-operation `security` auto-injected as FastAPI dependencies (Bearer JWT introspection included)
|
||
* 🧠 **Contract-first codegen** — `models` (Pydantic) and `routes` (resource stubs) generated from a spec
|
||
* 🧩 **Bundled templates** — `health_app`, `crud_app`, `model_app`, `vet_app` scaffolds for the whole lifecycle, from `/health` to SSE + multi-resource CRUD
|
||
|
||
---
|
||
|
||
## 📦 Installation
|
||
|
||
From your internal PyPI:
|
||
|
||
```bash
|
||
pip install --extra-index-url https://$PYPI_USERNAME:$PYPI_PASSWORD@pip.aetoskia.com/simple openapi-first
|
||
```
|
||
|
||
From local source:
|
||
|
||
```bash
|
||
pip install -e .
|
||
```
|
||
|
||
---
|
||
|
||
## 📁 Documentation Structure
|
||
|
||
| Section | Description |
|
||
|---------|-------------|
|
||
| [Overview](01_overview.md) | The mental model: spec as contract, `operationId` binding, fail-fast guarantees |
|
||
| [Components](02_components.md) | `app`, `binder`, `loader`, `client`, `errors`, `security`, `codegen`, `cli` |
|
||
| **Use cases** | Step-by-step recipes |
|
||
| · [01 – Quickstart](03_use_cases/01_quickstart.md) | Scaffold your first OpenAPI-first service |
|
||
| · [02 – Templates](03_use_cases/02_templates.md) | The bundled application templates and how to use them |
|
||
| · [03 – Client setup](03_use_cases/03_client.md) | Build an `operationId`-driven HTTP client |
|
||
| · [04 – Codegen](03_use_cases/04_codegen.md) | Generate Pydantic models and route stubs from a spec |
|
||
| [Design](04_design.md) | Architecture, responsibilities, and startup pipeline |
|
||
| [Security](05_security.md) | `securitySchemes`, env resolution, and JWT introspection |
|
||
| [Error Handling](06_error_handling.md) | The error hierarchy and when each error is raised |
|
||
| [Testing](07_testing.md) | Test strategy, quality gates, and coverage |
|
||
|
||
---
|
||
|
||
## 🔗 Related Resources
|
||
|
||
* **Source Code:** [Gitea Repository](https://git.aetoskia.com/aetos/openapi-first)
|
||
* **Internal PyPI:** [pip.aetoskia.com/simple/openapi-first](https://pip.aetoskia.com/simple/openapi-first)
|
||
* **Drone CI:** Auto-builds and publishes tagged releases, gated on black / ruff / mypy / pytest.
|
||
|
||
---
|
||
|
||
© Aetoskia Internal — `openapi-first` 0.0.6
|