Vishesh 'ironeagle' Bangotra
621f10409e
Squash-merge lib-standardisation: adopt repo standards across packaging, tooling, docs, and CI. - standardize pyproject.toml (canonical packaging, lint config, extras, GSDFC pydoclint) - add py.typed marker, modernize type hints and Google-style docstrings - nest generated docs under docs/lib and docs/mcp; add hand-written wiki - adopt standard Type A PyPI CI pipeline (tag==version guard + quality gate) - promote generated CHANGELOG.md; bump version to 0.0.7
3.3 KiB
3.3 KiB
🧩 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) - 🔗
operationIdbinding — handler functions are bound to routes purely byoperationId; 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-operationsecurityauto-injected as FastAPI dependencies (Bearer JWT introspection included) - 🧠 Contract-first codegen —
models(Pydantic) androutes(resource stubs) generated from a spec - 🧩 Bundled templates —
health_app,crud_app,model_app,vet_appscaffolds for the whole lifecycle, from/healthto 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