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