Skip to content

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

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

From local source:

1
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

© Aetoskia Internal — openapi-first 0.0.6