aetos/openapi-first
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

updated docs strings and added README.md

Browse Source
This commit is contained in:
Vishesh 'ironeagle' Bangotra
2026-03-08 17:59:52 +05:30
parent 80f8defcc2
commit 1c48f58578
23 changed files with 329 additions and 199 deletions
Download Patch File Download Diff File Expand all files Collapse all files

61
openapi_first/app.py
View File

@@ -1,32 +1,35 @@
"""
# Summary
OpenAPI-first application bootstrap for FastAPI.
---
## Summary
This module provides `OpenAPIFirstApp`, a thin but strict abstraction
that enforces OpenAPI as the single source of truth for a FastAPI service.
Notes:
**Core Principles:**
- The OpenAPI specification (JSON or YAML) defines the entire API surface
- Every operationId in the OpenAPI spec must have a corresponding Python handler function
- Handlers are plain Python callables (no FastAPI decorators)
- FastAPI route registration is derived exclusively from the spec
- FastAPI's autogenerated OpenAPI schema is fully overridden
- The OpenAPI specification (JSON or YAML) defines the entire API surface.
- Every `operationId` in the OpenAPI spec must have a corresponding
Python handler function.
- Handlers are plain Python callables (no FastAPI decorators).
- FastAPI route registration is derived exclusively from the spec.
- FastAPI's autogenerated OpenAPI schema is fully overridden.
**Responsibilities:**
- Loads and validates an OpenAPI 3.x specification
- Dynamically binds HTTP routes to handler functions using operationId
- Registers routes with FastAPI at application startup
- Ensures runtime behavior matches the OpenAPI contract exactly
- Loads and validates an OpenAPI 3.x specification.
- Dynamically binds HTTP routes to handler functions using `operationId`.
- Registers routes with FastAPI at application startup.
- Ensures runtime behavior matches the OpenAPI contract exactly.
**Constraints:**
- This module intentionally does NOT: Generate OpenAPI specs, generate client code, introduce a new framework or lifecycle, or alter FastAPI dependency injection semantics.
- This module intentionally does NOT:
- Generate OpenAPI specs.
- Generate client code.
- Introduce a new framework or lifecycle.
- Alter FastAPI dependency injection semantics.
"""
from fastapi import FastAPI
@@ -42,16 +45,19 @@ class OpenAPIFirstApp(FastAPI):
Notes:
**Responsibilities:**
- `OpenAPIFirstApp` subclasses FastAPI and replaces manual route registration with OpenAPI-driven binding
- All routes are derived from the provided OpenAPI specification, and each operationId is mapped to a Python function in the supplied routes module
- `OpenAPIFirstApp` subclasses `FastAPI` and replaces manual route
registration with OpenAPI-driven binding.
- All routes are derived from the provided OpenAPI specification,
and each `operationId` is mapped to a Python function in the
supplied routes module.
**Guarantees:**
- No route can exist without an OpenAPI declaration
- No OpenAPI operation can exist without a handler
- Swagger UI and `/openapi.json` always reflect the provided spec
- Handler functions remain framework-agnostic and testable
- No route can exist without an OpenAPI declaration.
- No OpenAPI operation can exist without a handler.
- Swagger UI and `/openapi.json` always reflect the provided spec.
- Handler functions remain framework-agnostic and testable.
Example:
```python
from openapi_first import OpenAPIFirstApp
@@ -77,15 +83,20 @@ class OpenAPIFirstApp(FastAPI):
Args:
openapi_path (str):
Filesystem path to the OpenAPI 3.x specification file. This specification is treated as the authoritative API contract.
Filesystem path to the OpenAPI 3.x specification file. This
specification is treated as the authoritative API contract.
routes_module (module):
Python module containing handler functions whose names correspond exactly to OpenAPI operationId values.
Python module containing handler functions whose names correspond
exactly to OpenAPI `operationId` values.
**fastapi_kwargs (Any):
Additional keyword arguments passed directly to `fastapi.FastAPI` (e.g., title, version, middleware, lifespan handlers).
Additional keyword arguments passed directly to
`fastapi.FastAPI` (e.g., title, version, middleware, lifespan
handlers).
Raises:
OpenAPIFirstError:
If the OpenAPI specification is invalid, or if any declared operationId does not have a corresponding handler function.
If the OpenAPI specification is invalid, or if any declared
`operationId` does not have a corresponding handler function.
"""
# Initialize FastAPI normally
super().__init__(**fastapi_kwargs)