docs: add OpenAPI-first wiki (overview, components, use cases for templates/client/codegen, design, security, error handling, testing) and refresh lib docs index

2026-09-15 22:29:05 +05:30
parent adeb02e162
commit b559323dfe
26 changed files with 1590 additions and 86 deletions
--- a/docs/wiki/index.md
+++ b/docs/wiki/index.md
@@ -0,0 +1,62 @@
+# 🧩 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