53 lines
5.2 KiB
JSON
53 lines
5.2 KiB
JSON
{
|
|
"module": "openapi_first.app",
|
|
"content": {
|
|
"path": "openapi_first.app",
|
|
"docstring": "OpenAPI-first application bootstrap for FastAPI.\n\n---\n\n## Summary\n\nThis module provides `OpenAPIFirstApp`, a thin but strict abstraction\nthat enforces OpenAPI as the single source of truth for a FastAPI service.\n\nNotes:\n **Core Principles:**\n\n - The OpenAPI specification (JSON or YAML) defines the entire API surface\n - Every operationId in the OpenAPI spec must have a corresponding Python handler function\n - Handlers are plain Python callables (no FastAPI decorators)\n - FastAPI route registration is derived exclusively from the spec\n - FastAPI's autogenerated OpenAPI schema is fully overridden\n\n **Responsibilities:**\n\n - Loads and validates an OpenAPI 3.x specification\n - Dynamically binds HTTP routes to handler functions using operationId\n - Registers routes with FastAPI at application startup\n - Ensures runtime behavior matches the OpenAPI contract exactly\n\n **Constraints:**\n\n - This module intentionally does NOT: Generate OpenAPI specs, generate client code, introduce a new framework or lifecycle, or alter FastAPI dependency injection semantics.",
|
|
"objects": {
|
|
"FastAPI": {
|
|
"name": "FastAPI",
|
|
"kind": "alias",
|
|
"path": "openapi_first.app.FastAPI",
|
|
"signature": "<bound method Alias.signature of Alias('FastAPI', 'fastapi.FastAPI')>",
|
|
"docstring": null
|
|
},
|
|
"load_openapi": {
|
|
"name": "load_openapi",
|
|
"kind": "function",
|
|
"path": "openapi_first.app.load_openapi",
|
|
"signature": "<bound method Alias.signature of Alias('load_openapi', 'openapi_first.loader.load_openapi')>",
|
|
"docstring": "Load and validate an OpenAPI 3.x specification from disk.\n\nArgs:\n path (str | Path):\n Filesystem path to an OpenAPI specification file. Supported extensions: .json, .yaml, .yml.\n\nReturns:\n dict[str, Any]:\n Parsed and validated OpenAPI specification.\n\nRaises:\n OpenAPISpecLoadError:\n If the file does not exist, cannot be parsed, or fails OpenAPI schema validation.\n\nNotes:\n **Guarantees:**\n\n - The specification is parsed based on file extension and validated using a strict OpenAPI schema validator\n - Any error results in an immediate exception, preventing application startup"
|
|
},
|
|
"bind_routes": {
|
|
"name": "bind_routes",
|
|
"kind": "function",
|
|
"path": "openapi_first.app.bind_routes",
|
|
"signature": "<bound method Alias.signature of Alias('bind_routes', 'openapi_first.binder.bind_routes')>",
|
|
"docstring": "Bind OpenAPI operations to FastAPI routes.\n\nArgs:\n app (fastapi.FastAPI):\n The FastAPI application instance to which routes will be added.\n spec (dict):\n Parsed OpenAPI 3.x specification dictionary.\n routes_module (module):\n Python module containing handler functions. Each handler's name MUST exactly match an OpenAPI operationId.\n\nRaises:\n MissingOperationHandler:\n If an operationId is missing from the spec or if no corresponding handler function exists in the routes module.\n\nNotes:\n **Responsibilities:**\n\n - Iterates through the OpenAPI specification paths and methods\n - Resolves each operationId to a handler function, and registers a corresponding APIRoute on the FastAPI application\n\n **Guarantees:**\n\n - Route registration is deterministic and spec-driven. No route decorators are required or supported. Handler resolution errors surface at application startup."
|
|
},
|
|
"OpenAPIFirstApp": {
|
|
"name": "OpenAPIFirstApp",
|
|
"kind": "class",
|
|
"path": "openapi_first.app.OpenAPIFirstApp",
|
|
"signature": "<bound method Class.signature of Class('OpenAPIFirstApp', 38, 104)>",
|
|
"docstring": "FastAPI application enforcing OpenAPI-first design.\n\nNotes:\n **Responsibilities:**\n\n - `OpenAPIFirstApp` subclasses FastAPI and replaces manual route registration with OpenAPI-driven binding\n - All routes are derived from the provided OpenAPI specification, and each operationId is mapped to a Python function in the supplied routes module\n\n **Guarantees:**\n\n - No route can exist without an OpenAPI declaration\n - No OpenAPI operation can exist without a handler\n - Swagger UI and `/openapi.json` always reflect the provided spec\n - Handler functions remain framework-agnostic and testable\n\nExample:\n ```python\n from openapi_first import OpenAPIFirstApp\n import app.routes as routes\n\n app = OpenAPIFirstApp(\n openapi_path=\"app/openapi.json\",\n routes_module=routes,\n title=\"Example Service\",\n )\n ```",
|
|
"members": {
|
|
"openapi": {
|
|
"name": "openapi",
|
|
"kind": "attribute",
|
|
"path": "openapi_first.app.OpenAPIFirstApp.openapi",
|
|
"signature": null,
|
|
"docstring": null
|
|
}
|
|
}
|
|
},
|
|
"Any": {
|
|
"name": "Any",
|
|
"kind": "alias",
|
|
"path": "openapi_first.app.Any",
|
|
"signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
|
|
"docstring": null
|
|
}
|
|
}
|
|
}
|
|
} |