openapi-first/docs/wiki/index.md

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

pip install --extra-index-url https://$PYPI_USERNAME:$PYPI_PASSWORD@pip.aetoskia.com/simple openapi-first

From local source:

pip install -e .

---

📁 Documentation Structure

Section	Description
Overview	The mental model: spec as contract, operationId binding, fail-fast guarantees
Components	app, binder, loader, client, errors, security, codegen, cli
Use cases	Step-by-step recipes
· 01 – Quickstart	Scaffold your first OpenAPI-first service
· 02 – Templates	The bundled application templates and how to use them
· 03 – Client setup	Build an operationId-driven HTTP client
· 04 – Codegen	Generate Pydantic models and route stubs from a spec
Design	Architecture, responsibilities, and startup pipeline
Security	securitySchemes, env resolution, and JWT introspection
Error Handling	The error hierarchy and when each error is raised
Testing	Test strategy, quality gates, and coverage

---

🔗 Related Resources

• Source Code: Gitea Repository
• Internal PyPI: 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