From 294f3d7a0c6d665b940c85029b37e48b48c99674 Mon Sep 17 00:00:00 2001 From: Vishesh 'ironeagle' Bangotra Date: Sun, 13 Sep 2026 16:21:07 +0530 Subject: [PATCH] fix: apply GSDFC docstring conformance, add minimal annotations to unannotated params (pydoclint zero); refresh lib/MCP docs --- docs/lib/index.md | 1 + docs/lib/openapi_first/app.md | 3 + docs/lib/openapi_first/binder.md | 3 + docs/lib/openapi_first/cli.md | 3 + docs/lib/openapi_first/client.md | 3 + docs/lib/openapi_first/codegen.md | 3 + docs/lib/openapi_first/codegen_routes.md | 3 + docs/lib/openapi_first/errors.md | 3 + docs/lib/openapi_first/index.md | 13 ++++ docs/lib/openapi_first/loader.md | 3 + docs/lib/openapi_first/security.md | 3 + .../openapi_first/templates/crud_app/data.md | 3 + .../openapi_first/templates/crud_app/index.md | 7 ++ .../openapi_first/templates/crud_app/main.md | 3 + .../templates/crud_app/routes.md | 3 + .../templates/crud_app/test_crud_app.md | 3 + .../templates/health_app/index.md | 5 ++ .../templates/health_app/main.md | 3 + .../templates/health_app/routes.md | 3 + docs/lib/openapi_first/templates/index.md | 7 ++ .../openapi_first/templates/model_app/data.md | 3 + .../templates/model_app/index.md | 8 +++ .../openapi_first/templates/model_app/main.md | 3 + .../templates/model_app/models.md | 3 + .../templates/model_app/routes.md | 3 + .../templates/model_app/test_model_app.md | 3 + .../openapi_first/templates/vet_app/data.md | 3 + .../openapi_first/templates/vet_app/index.md | 9 +++ .../openapi_first/templates/vet_app/main.md | 3 + .../openapi_first/templates/vet_app/models.md | 3 + .../openapi_first/templates/vet_app/routes.md | 3 + .../openapi_first/templates/vet_app/sse.md | 3 + .../templates/vet_app/test_vet_app.md | 3 + docs/mcp/modules/openapi_first.app.json | 18 +++--- docs/mcp/modules/openapi_first.binder.json | 2 +- docs/mcp/modules/openapi_first.cli.json | 8 +-- docs/mcp/modules/openapi_first.codegen.json | 2 +- .../modules/openapi_first.codegen_routes.json | 6 +- docs/mcp/modules/openapi_first.json | 42 ++++++------ docs/mcp/modules/openapi_first.security.json | 6 +- docs/mcp/nav.json | 64 +++++++++---------- openapi_first/app.py | 7 +- openapi_first/binder.py | 10 +-- openapi_first/cli.py | 6 +- openapi_first/client.py | 4 +- openapi_first/codegen_routes.py | 10 +-- openapi_first/errors.py | 2 +- openapi_first/security.py | 9 ++- 48 files changed, 228 insertions(+), 96 deletions(-) create mode 100644 docs/lib/openapi_first/app.md create mode 100644 docs/lib/openapi_first/binder.md create mode 100644 docs/lib/openapi_first/cli.md create mode 100644 docs/lib/openapi_first/client.md create mode 100644 docs/lib/openapi_first/codegen.md create mode 100644 docs/lib/openapi_first/codegen_routes.md create mode 100644 docs/lib/openapi_first/errors.md create mode 100644 docs/lib/openapi_first/index.md create mode 100644 docs/lib/openapi_first/loader.md create mode 100644 docs/lib/openapi_first/security.md create mode 100644 docs/lib/openapi_first/templates/crud_app/data.md create mode 100644 docs/lib/openapi_first/templates/crud_app/index.md create mode 100644 docs/lib/openapi_first/templates/crud_app/main.md create mode 100644 docs/lib/openapi_first/templates/crud_app/routes.md create mode 100644 docs/lib/openapi_first/templates/crud_app/test_crud_app.md create mode 100644 docs/lib/openapi_first/templates/health_app/index.md create mode 100644 docs/lib/openapi_first/templates/health_app/main.md create mode 100644 docs/lib/openapi_first/templates/health_app/routes.md create mode 100644 docs/lib/openapi_first/templates/index.md create mode 100644 docs/lib/openapi_first/templates/model_app/data.md create mode 100644 docs/lib/openapi_first/templates/model_app/index.md create mode 100644 docs/lib/openapi_first/templates/model_app/main.md create mode 100644 docs/lib/openapi_first/templates/model_app/models.md create mode 100644 docs/lib/openapi_first/templates/model_app/routes.md create mode 100644 docs/lib/openapi_first/templates/model_app/test_model_app.md create mode 100644 docs/lib/openapi_first/templates/vet_app/data.md create mode 100644 docs/lib/openapi_first/templates/vet_app/index.md create mode 100644 docs/lib/openapi_first/templates/vet_app/main.md create mode 100644 docs/lib/openapi_first/templates/vet_app/models.md create mode 100644 docs/lib/openapi_first/templates/vet_app/routes.md create mode 100644 docs/lib/openapi_first/templates/vet_app/sse.md create mode 100644 docs/lib/openapi_first/templates/vet_app/test_vet_app.md diff --git a/docs/lib/index.md b/docs/lib/index.md index ee4b379..767439d 100644 --- a/docs/lib/index.md +++ b/docs/lib/index.md @@ -1,3 +1,4 @@ # openapi_first ::: openapi_first +- [Openapi First](openapi_first/) diff --git a/docs/lib/openapi_first/app.md b/docs/lib/openapi_first/app.md new file mode 100644 index 0000000..f289c43 --- /dev/null +++ b/docs/lib/openapi_first/app.md @@ -0,0 +1,3 @@ +# App + +::: openapi_first.app diff --git a/docs/lib/openapi_first/binder.md b/docs/lib/openapi_first/binder.md new file mode 100644 index 0000000..045baf3 --- /dev/null +++ b/docs/lib/openapi_first/binder.md @@ -0,0 +1,3 @@ +# Binder + +::: openapi_first.binder diff --git a/docs/lib/openapi_first/cli.md b/docs/lib/openapi_first/cli.md new file mode 100644 index 0000000..eaaadc2 --- /dev/null +++ b/docs/lib/openapi_first/cli.md @@ -0,0 +1,3 @@ +# Cli + +::: openapi_first.cli diff --git a/docs/lib/openapi_first/client.md b/docs/lib/openapi_first/client.md new file mode 100644 index 0000000..53f019e --- /dev/null +++ b/docs/lib/openapi_first/client.md @@ -0,0 +1,3 @@ +# Client + +::: openapi_first.client diff --git a/docs/lib/openapi_first/codegen.md b/docs/lib/openapi_first/codegen.md new file mode 100644 index 0000000..44b1cdc --- /dev/null +++ b/docs/lib/openapi_first/codegen.md @@ -0,0 +1,3 @@ +# Codegen + +::: openapi_first.codegen diff --git a/docs/lib/openapi_first/codegen_routes.md b/docs/lib/openapi_first/codegen_routes.md new file mode 100644 index 0000000..3301add --- /dev/null +++ b/docs/lib/openapi_first/codegen_routes.md @@ -0,0 +1,3 @@ +# Codegen Routes + +::: openapi_first.codegen_routes diff --git a/docs/lib/openapi_first/errors.md b/docs/lib/openapi_first/errors.md new file mode 100644 index 0000000..fe3b381 --- /dev/null +++ b/docs/lib/openapi_first/errors.md @@ -0,0 +1,3 @@ +# Errors + +::: openapi_first.errors diff --git a/docs/lib/openapi_first/index.md b/docs/lib/openapi_first/index.md new file mode 100644 index 0000000..f4c28dd --- /dev/null +++ b/docs/lib/openapi_first/index.md @@ -0,0 +1,13 @@ +# Openapi First + +::: openapi_first +- [App](app.md) +- [Binder](binder.md) +- [Cli](cli.md) +- [Client](client.md) +- [Codegen](codegen.md) +- [Codegen Routes](codegen_routes.md) +- [Errors](errors.md) +- [Loader](loader.md) +- [Security](security.md) +- [Templates](templates/) diff --git a/docs/lib/openapi_first/loader.md b/docs/lib/openapi_first/loader.md new file mode 100644 index 0000000..f557311 --- /dev/null +++ b/docs/lib/openapi_first/loader.md @@ -0,0 +1,3 @@ +# Loader + +::: openapi_first.loader diff --git a/docs/lib/openapi_first/security.md b/docs/lib/openapi_first/security.md new file mode 100644 index 0000000..3a8a166 --- /dev/null +++ b/docs/lib/openapi_first/security.md @@ -0,0 +1,3 @@ +# Security + +::: openapi_first.security diff --git a/docs/lib/openapi_first/templates/crud_app/data.md b/docs/lib/openapi_first/templates/crud_app/data.md new file mode 100644 index 0000000..df37dde --- /dev/null +++ b/docs/lib/openapi_first/templates/crud_app/data.md @@ -0,0 +1,3 @@ +# Data + +::: openapi_first.templates.crud_app.data diff --git a/docs/lib/openapi_first/templates/crud_app/index.md b/docs/lib/openapi_first/templates/crud_app/index.md new file mode 100644 index 0000000..f8d5e4b --- /dev/null +++ b/docs/lib/openapi_first/templates/crud_app/index.md @@ -0,0 +1,7 @@ +# Crud App + +::: openapi_first.templates.crud_app +- [Data](data.md) +- [Main](main.md) +- [Routes](routes.md) +- [Test Crud App](test_crud_app.md) diff --git a/docs/lib/openapi_first/templates/crud_app/main.md b/docs/lib/openapi_first/templates/crud_app/main.md new file mode 100644 index 0000000..a2673ae --- /dev/null +++ b/docs/lib/openapi_first/templates/crud_app/main.md @@ -0,0 +1,3 @@ +# Main + +::: openapi_first.templates.crud_app.main diff --git a/docs/lib/openapi_first/templates/crud_app/routes.md b/docs/lib/openapi_first/templates/crud_app/routes.md new file mode 100644 index 0000000..2950fcc --- /dev/null +++ b/docs/lib/openapi_first/templates/crud_app/routes.md @@ -0,0 +1,3 @@ +# Routes + +::: openapi_first.templates.crud_app.routes diff --git a/docs/lib/openapi_first/templates/crud_app/test_crud_app.md b/docs/lib/openapi_first/templates/crud_app/test_crud_app.md new file mode 100644 index 0000000..b876492 --- /dev/null +++ b/docs/lib/openapi_first/templates/crud_app/test_crud_app.md @@ -0,0 +1,3 @@ +# Test Crud App + +::: openapi_first.templates.crud_app.test_crud_app diff --git a/docs/lib/openapi_first/templates/health_app/index.md b/docs/lib/openapi_first/templates/health_app/index.md new file mode 100644 index 0000000..3569665 --- /dev/null +++ b/docs/lib/openapi_first/templates/health_app/index.md @@ -0,0 +1,5 @@ +# Health App + +::: openapi_first.templates.health_app +- [Main](main.md) +- [Routes](routes.md) diff --git a/docs/lib/openapi_first/templates/health_app/main.md b/docs/lib/openapi_first/templates/health_app/main.md new file mode 100644 index 0000000..bf0fa94 --- /dev/null +++ b/docs/lib/openapi_first/templates/health_app/main.md @@ -0,0 +1,3 @@ +# Main + +::: openapi_first.templates.health_app.main diff --git a/docs/lib/openapi_first/templates/health_app/routes.md b/docs/lib/openapi_first/templates/health_app/routes.md new file mode 100644 index 0000000..96bcfde --- /dev/null +++ b/docs/lib/openapi_first/templates/health_app/routes.md @@ -0,0 +1,3 @@ +# Routes + +::: openapi_first.templates.health_app.routes diff --git a/docs/lib/openapi_first/templates/index.md b/docs/lib/openapi_first/templates/index.md new file mode 100644 index 0000000..8489336 --- /dev/null +++ b/docs/lib/openapi_first/templates/index.md @@ -0,0 +1,7 @@ +# Templates + +::: openapi_first.templates +- [Crud App](crud_app/) +- [Health App](health_app/) +- [Model App](model_app/) +- [Vet App](vet_app/) diff --git a/docs/lib/openapi_first/templates/model_app/data.md b/docs/lib/openapi_first/templates/model_app/data.md new file mode 100644 index 0000000..d26cb7a --- /dev/null +++ b/docs/lib/openapi_first/templates/model_app/data.md @@ -0,0 +1,3 @@ +# Data + +::: openapi_first.templates.model_app.data diff --git a/docs/lib/openapi_first/templates/model_app/index.md b/docs/lib/openapi_first/templates/model_app/index.md new file mode 100644 index 0000000..957c078 --- /dev/null +++ b/docs/lib/openapi_first/templates/model_app/index.md @@ -0,0 +1,8 @@ +# Model App + +::: openapi_first.templates.model_app +- [Data](data.md) +- [Main](main.md) +- [Models](models.md) +- [Routes](routes.md) +- [Test Model App](test_model_app.md) diff --git a/docs/lib/openapi_first/templates/model_app/main.md b/docs/lib/openapi_first/templates/model_app/main.md new file mode 100644 index 0000000..1434dc4 --- /dev/null +++ b/docs/lib/openapi_first/templates/model_app/main.md @@ -0,0 +1,3 @@ +# Main + +::: openapi_first.templates.model_app.main diff --git a/docs/lib/openapi_first/templates/model_app/models.md b/docs/lib/openapi_first/templates/model_app/models.md new file mode 100644 index 0000000..ba61897 --- /dev/null +++ b/docs/lib/openapi_first/templates/model_app/models.md @@ -0,0 +1,3 @@ +# Models + +::: openapi_first.templates.model_app.models diff --git a/docs/lib/openapi_first/templates/model_app/routes.md b/docs/lib/openapi_first/templates/model_app/routes.md new file mode 100644 index 0000000..7bc6e3c --- /dev/null +++ b/docs/lib/openapi_first/templates/model_app/routes.md @@ -0,0 +1,3 @@ +# Routes + +::: openapi_first.templates.model_app.routes diff --git a/docs/lib/openapi_first/templates/model_app/test_model_app.md b/docs/lib/openapi_first/templates/model_app/test_model_app.md new file mode 100644 index 0000000..36c6a81 --- /dev/null +++ b/docs/lib/openapi_first/templates/model_app/test_model_app.md @@ -0,0 +1,3 @@ +# Test Model App + +::: openapi_first.templates.model_app.test_model_app diff --git a/docs/lib/openapi_first/templates/vet_app/data.md b/docs/lib/openapi_first/templates/vet_app/data.md new file mode 100644 index 0000000..1117bf0 --- /dev/null +++ b/docs/lib/openapi_first/templates/vet_app/data.md @@ -0,0 +1,3 @@ +# Data + +::: openapi_first.templates.vet_app.data diff --git a/docs/lib/openapi_first/templates/vet_app/index.md b/docs/lib/openapi_first/templates/vet_app/index.md new file mode 100644 index 0000000..bc93f9d --- /dev/null +++ b/docs/lib/openapi_first/templates/vet_app/index.md @@ -0,0 +1,9 @@ +# Vet App + +::: openapi_first.templates.vet_app +- [Data](data.md) +- [Main](main.md) +- [Models](models.md) +- [Routes](routes.md) +- [Sse](sse.md) +- [Test Vet App](test_vet_app.md) diff --git a/docs/lib/openapi_first/templates/vet_app/main.md b/docs/lib/openapi_first/templates/vet_app/main.md new file mode 100644 index 0000000..e253dad --- /dev/null +++ b/docs/lib/openapi_first/templates/vet_app/main.md @@ -0,0 +1,3 @@ +# Main + +::: openapi_first.templates.vet_app.main diff --git a/docs/lib/openapi_first/templates/vet_app/models.md b/docs/lib/openapi_first/templates/vet_app/models.md new file mode 100644 index 0000000..d65ce55 --- /dev/null +++ b/docs/lib/openapi_first/templates/vet_app/models.md @@ -0,0 +1,3 @@ +# Models + +::: openapi_first.templates.vet_app.models diff --git a/docs/lib/openapi_first/templates/vet_app/routes.md b/docs/lib/openapi_first/templates/vet_app/routes.md new file mode 100644 index 0000000..8d99bc4 --- /dev/null +++ b/docs/lib/openapi_first/templates/vet_app/routes.md @@ -0,0 +1,3 @@ +# Routes + +::: openapi_first.templates.vet_app.routes diff --git a/docs/lib/openapi_first/templates/vet_app/sse.md b/docs/lib/openapi_first/templates/vet_app/sse.md new file mode 100644 index 0000000..6e3e4e4 --- /dev/null +++ b/docs/lib/openapi_first/templates/vet_app/sse.md @@ -0,0 +1,3 @@ +# Sse + +::: openapi_first.templates.vet_app.sse diff --git a/docs/lib/openapi_first/templates/vet_app/test_vet_app.md b/docs/lib/openapi_first/templates/vet_app/test_vet_app.md new file mode 100644 index 0000000..8aebee7 --- /dev/null +++ b/docs/lib/openapi_first/templates/vet_app/test_vet_app.md @@ -0,0 +1,3 @@ +# Test Vet App + +::: openapi_first.templates.vet_app.test_vet_app diff --git a/docs/mcp/modules/openapi_first.app.json b/docs/mcp/modules/openapi_first.app.json index 6ed98ac..c8df6bc 100644 --- a/docs/mcp/modules/openapi_first.app.json +++ b/docs/mcp/modules/openapi_first.app.json @@ -18,6 +18,13 @@ "signature": "", "docstring": null }, + "Any": { + "name": "Any", + "kind": "alias", + "path": "openapi_first.app.Any", + "signature": "", + "docstring": null + }, "FastAPI": { "name": "FastAPI", "kind": "alias", @@ -30,7 +37,7 @@ "kind": "function", "path": "openapi_first.app.bind_routes", "signature": "", - "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\n exactly match an OpenAPI `operationId`.\n security_deps (dict | None):\n Optional mapping of ``METHOD:/path`` → ``list[Depends(...)]``\n generated from the spec's ``securitySchemes`` and per-operation\n ``security`` fields.\n\nRaises:\n MissingOperationHandler:\n If an ``operationId`` is missing from the spec or if no corresponding\n 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\n a corresponding ``APIRoute`` on the FastAPI application.\n - Injects FastAPI ``Depends()`` for each security requirement found\n on the operation or inherited from the top-level ``security`` field.\n\n **Guarantees:**\n\n - Route registration is deterministic and spec-driven. No route\n decorators are required or supported. Handler resolution errors\n surface at application startup." + "docstring": "Bind OpenAPI operations to FastAPI routes.\n\nArgs:\n app (Any):\n The FastAPI application instance to which routes will be added.\n spec (dict):\n Parsed OpenAPI 3.x specification dictionary.\n routes_module (Any):\n Python module containing handler functions. Each handler's name MUST\n exactly match an OpenAPI `operationId`.\n security_deps (dict[str, list[Any]] | None):\n Optional mapping of ``METHOD:/path`` → ``list[Depends(...)]``\n generated from the spec's ``securitySchemes`` and per-operation\n ``security`` fields.\n\nRaises:\n MissingOperationHandler:\n If an ``operationId`` is missing from the spec or if no corresponding\n 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\n a corresponding ``APIRoute`` on the FastAPI application.\n - Injects FastAPI ``Depends()`` for each security requirement found\n on the operation or inherited from the top-level ``security`` field.\n\n **Guarantees:**\n\n - Route registration is deterministic and spec-driven. No route\n decorators are required or supported. Handler resolution errors\n surface at application startup." }, "load_openapi": { "name": "load_openapi", @@ -57,7 +64,7 @@ "name": "OpenAPIFirstApp", "kind": "class", "path": "openapi_first.app.OpenAPIFirstApp", - "signature": "", + "signature": "", "docstring": "FastAPI application enforcing OpenAPI-first design.\n\nNotes:\n **Responsibilities:**\n\n - `OpenAPIFirstApp` subclasses `FastAPI` and replaces manual route\n registration with OpenAPI-driven binding.\n - All routes are derived from the provided OpenAPI specification,\n and each ``operationId`` is mapped to a Python function in the\n supplied routes module.\n - Auth dependencies are auto-injected from the spec's\n ``securitySchemes`` and per-operation ``security`` fields.\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 - Auth enforcement is driven entirely by the spec — no manual\n middleware or decorators required.\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": { @@ -68,13 +75,6 @@ "docstring": null } } - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "openapi_first.app.Any", - "signature": "", - "docstring": null } } } diff --git a/docs/mcp/modules/openapi_first.binder.json b/docs/mcp/modules/openapi_first.binder.json index beb8d21..7fe0ba1 100644 --- a/docs/mcp/modules/openapi_first.binder.json +++ b/docs/mcp/modules/openapi_first.binder.json @@ -30,7 +30,7 @@ "kind": "function", "path": "openapi_first.binder.bind_routes", "signature": "", - "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\n exactly match an OpenAPI `operationId`.\n security_deps (dict | None):\n Optional mapping of ``METHOD:/path`` → ``list[Depends(...)]``\n generated from the spec's ``securitySchemes`` and per-operation\n ``security`` fields.\n\nRaises:\n MissingOperationHandler:\n If an ``operationId`` is missing from the spec or if no corresponding\n 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\n a corresponding ``APIRoute`` on the FastAPI application.\n - Injects FastAPI ``Depends()`` for each security requirement found\n on the operation or inherited from the top-level ``security`` field.\n\n **Guarantees:**\n\n - Route registration is deterministic and spec-driven. No route\n decorators are required or supported. Handler resolution errors\n surface at application startup." + "docstring": "Bind OpenAPI operations to FastAPI routes.\n\nArgs:\n app (Any):\n The FastAPI application instance to which routes will be added.\n spec (dict):\n Parsed OpenAPI 3.x specification dictionary.\n routes_module (Any):\n Python module containing handler functions. Each handler's name MUST\n exactly match an OpenAPI `operationId`.\n security_deps (dict[str, list[Any]] | None):\n Optional mapping of ``METHOD:/path`` → ``list[Depends(...)]``\n generated from the spec's ``securitySchemes`` and per-operation\n ``security`` fields.\n\nRaises:\n MissingOperationHandler:\n If an ``operationId`` is missing from the spec or if no corresponding\n 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\n a corresponding ``APIRoute`` on the FastAPI application.\n - Injects FastAPI ``Depends()`` for each security requirement found\n on the operation or inherited from the top-level ``security`` field.\n\n **Guarantees:**\n\n - Route registration is deterministic and spec-driven. No route\n decorators are required or supported. Handler resolution errors\n surface at application startup." }, "FastAPI": { "name": "FastAPI", diff --git a/docs/mcp/modules/openapi_first.cli.json b/docs/mcp/modules/openapi_first.cli.json index 4ada4ed..f77f555 100644 --- a/docs/mcp/modules/openapi_first.cli.json +++ b/docs/mcp/modules/openapi_first.cli.json @@ -2,7 +2,7 @@ "module": "openapi_first.cli", "content": { "path": "openapi_first.cli", - "docstring": "Command-line interface for FastAPI OpenAPI-first scaffolding utilities.\n\n---\n\n## Summary\n\nThis CLI bootstraps OpenAPI-first FastAPI applications from versioned,\nbundled templates packaged with the library.", + "docstring": "# Summary\n\nCommand-line interface for FastAPI OpenAPI-first scaffolding utilities.\n\nThis CLI bootstraps OpenAPI-first FastAPI applications from versioned,\nbundled templates packaged with the library.", "objects": { "argparse": { "name": "argparse", @@ -43,21 +43,21 @@ "name": "available_templates", "kind": "function", "path": "openapi_first.cli.available_templates", - "signature": "", + "signature": "", "docstring": "Return a list of available application templates.\n\nReturns:\n list[str]:\n Sorted list of template names found in the internal templates directory." }, "copy_template": { "name": "copy_template", "kind": "function", "path": "openapi_first.cli.copy_template", - "signature": "", + "signature": "", "docstring": "Copy a bundled OpenAPI-first application template into a directory.\n\nArgs:\n template (str):\n Name of the template to copy.\n target_dir (Path):\n Filesystem path where the template should be copied.\n\nRaises:\n FileNotFoundError:\n If the requested template does not exist." }, "main": { "name": "main", "kind": "function", "path": "openapi_first.cli.main", - "signature": "", + "signature": "", "docstring": null } } diff --git a/docs/mcp/modules/openapi_first.codegen.json b/docs/mcp/modules/openapi_first.codegen.json index 5fc9763..bc8ba9d 100644 --- a/docs/mcp/modules/openapi_first.codegen.json +++ b/docs/mcp/modules/openapi_first.codegen.json @@ -37,7 +37,7 @@ "kind": "function", "path": "openapi_first.codegen.generate_routes", "signature": "", - "docstring": "Generate route handler stubs from an OpenAPI specification.\n\nCreates one ``.py`` file per resource in *output_dir*.\nResources are derived from the first path segment (e.g. ``/pets``\nand ``/pets/{id}`` both group under ``pets``).\n\nArgs:\n spec_path:\n Path to the OpenAPI specification file (YAML or JSON).\n output_dir:\n Directory where the generated route files are written.\n Created automatically if it does not exist.\n use_models:\n If ``True``, import Pydantic models from *models_module*\n for request-body schemas referenced via ``$ref``.\n models_module:\n Dotted Python module path from which to import models\n (e.g. ``\"models\"``, ``\"app.models\"``).\n\nReturns:\n list[Path]:\n Absolute paths of every generated route file.\n\nRaises:\n OpenAPISpecLoadError:\n If the spec cannot be loaded or validated.\n ValueError:\n If any operation is missing ``operationId``." + "docstring": "Generate route handler stubs from an OpenAPI specification.\n\nCreates one ``.py`` file per resource in *output_dir*.\nResources are derived from the first path segment (e.g. ``/pets``\nand ``/pets/{id}`` both group under ``pets``).\n\nArgs:\n spec_path (Path):\n Path to the OpenAPI specification file (YAML or JSON).\n output_dir (Path):\n Directory where the generated route files are written.\n Created automatically if it does not exist.\n use_models (bool, optional):\n If ``True``, import Pydantic models from *models_module*\n for request-body schemas referenced via ``$ref``.\n models_module (str, optional):\n Dotted Python module path from which to import models\n (e.g. ``\"models\"``, ``\"app.models\"``).\n\nReturns:\n list[Path]:\n Absolute paths of every generated route file.\n\nRaises:\n OpenAPISpecLoadError:\n If the spec cannot be loaded or validated.\n ValueError:\n If any operation is missing ``operationId``." }, "generate_models": { "name": "generate_models", diff --git a/docs/mcp/modules/openapi_first.codegen_routes.json b/docs/mcp/modules/openapi_first.codegen_routes.json index 539d673..77db335 100644 --- a/docs/mcp/modules/openapi_first.codegen_routes.json +++ b/docs/mcp/modules/openapi_first.codegen_routes.json @@ -2,7 +2,7 @@ "module": "openapi_first.codegen_routes", "content": { "path": "openapi_first.codegen_routes", - "docstring": "Route handler code generation from OpenAPI specifications.\n\nThis module generates Python route handler stubs from an OpenAPI 3.x\nspecification. Each resource (derived from the first path segment)\ngets its own file under the output directory. Every OpenAPI operation\nmust define an ``operationId``, which becomes the handler function name.\n\nNotes:\n **Design constraints:**\n\n - ``operationId`` is required on every operation (matching\n ``binder.bind_routes``).\n - Handlers are stubs raising ``NotImplementedError``.\n - Sub-resources (e.g. ``/pets/{id}/photo``) are grouped with their\n parent resource (``pets``).\n - Parameter types and defaults are inferred from the spec.\n - ``response: Response`` is injected for non-200 success codes.", + "docstring": "# Summary\n\nRoute handler code generation from OpenAPI specifications.\n\nThis module generates Python route handler stubs from an OpenAPI 3.x\nspecification. Each resource (derived from the first path segment)\ngets its own file under the output directory. Every OpenAPI operation\nmust define an ``operationId``, which becomes the handler function name.\n\nNotes:\n **Design constraints:**\n\n - ``operationId`` is required on every operation (matching\n ``binder.bind_routes``).\n - Handlers are stubs raising ``NotImplementedError``.\n - Sub-resources (e.g. ``/pets/{id}/photo``) are grouped with their\n parent resource (``pets``).\n - Parameter types and defaults are inferred from the spec.\n - ``response: Response`` is injected for non-200 success codes.", "objects": { "Path": { "name": "Path", @@ -29,8 +29,8 @@ "name": "generate_routes", "kind": "function", "path": "openapi_first.codegen_routes.generate_routes", - "signature": "", - "docstring": "Generate route handler stubs from an OpenAPI specification.\n\nCreates one ``.py`` file per resource in *output_dir*.\nResources are derived from the first path segment (e.g. ``/pets``\nand ``/pets/{id}`` both group under ``pets``).\n\nArgs:\n spec_path:\n Path to the OpenAPI specification file (YAML or JSON).\n output_dir:\n Directory where the generated route files are written.\n Created automatically if it does not exist.\n use_models:\n If ``True``, import Pydantic models from *models_module*\n for request-body schemas referenced via ``$ref``.\n models_module:\n Dotted Python module path from which to import models\n (e.g. ``\"models\"``, ``\"app.models\"``).\n\nReturns:\n list[Path]:\n Absolute paths of every generated route file.\n\nRaises:\n OpenAPISpecLoadError:\n If the spec cannot be loaded or validated.\n ValueError:\n If any operation is missing ``operationId``." + "signature": "", + "docstring": "Generate route handler stubs from an OpenAPI specification.\n\nCreates one ``.py`` file per resource in *output_dir*.\nResources are derived from the first path segment (e.g. ``/pets``\nand ``/pets/{id}`` both group under ``pets``).\n\nArgs:\n spec_path (Path):\n Path to the OpenAPI specification file (YAML or JSON).\n output_dir (Path):\n Directory where the generated route files are written.\n Created automatically if it does not exist.\n use_models (bool, optional):\n If ``True``, import Pydantic models from *models_module*\n for request-body schemas referenced via ``$ref``.\n models_module (str, optional):\n Dotted Python module path from which to import models\n (e.g. ``\"models\"``, ``\"app.models\"``).\n\nReturns:\n list[Path]:\n Absolute paths of every generated route file.\n\nRaises:\n OpenAPISpecLoadError:\n If the spec cannot be loaded or validated.\n ValueError:\n If any operation is missing ``operationId``." } } } diff --git a/docs/mcp/modules/openapi_first.json b/docs/mcp/modules/openapi_first.json index 5a884cf..a9d481e 100644 --- a/docs/mcp/modules/openapi_first.json +++ b/docs/mcp/modules/openapi_first.json @@ -25,6 +25,13 @@ "signature": "", "docstring": null }, + "Any": { + "name": "Any", + "kind": "alias", + "path": "openapi_first.app.Any", + "signature": "", + "docstring": null + }, "FastAPI": { "name": "FastAPI", "kind": "alias", @@ -37,7 +44,7 @@ "kind": "function", "path": "openapi_first.app.bind_routes", "signature": "", - "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\n exactly match an OpenAPI `operationId`.\n security_deps (dict | None):\n Optional mapping of ``METHOD:/path`` → ``list[Depends(...)]``\n generated from the spec's ``securitySchemes`` and per-operation\n ``security`` fields.\n\nRaises:\n MissingOperationHandler:\n If an ``operationId`` is missing from the spec or if no corresponding\n 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\n a corresponding ``APIRoute`` on the FastAPI application.\n - Injects FastAPI ``Depends()`` for each security requirement found\n on the operation or inherited from the top-level ``security`` field.\n\n **Guarantees:**\n\n - Route registration is deterministic and spec-driven. No route\n decorators are required or supported. Handler resolution errors\n surface at application startup." + "docstring": "Bind OpenAPI operations to FastAPI routes.\n\nArgs:\n app (Any):\n The FastAPI application instance to which routes will be added.\n spec (dict):\n Parsed OpenAPI 3.x specification dictionary.\n routes_module (Any):\n Python module containing handler functions. Each handler's name MUST\n exactly match an OpenAPI `operationId`.\n security_deps (dict[str, list[Any]] | None):\n Optional mapping of ``METHOD:/path`` → ``list[Depends(...)]``\n generated from the spec's ``securitySchemes`` and per-operation\n ``security`` fields.\n\nRaises:\n MissingOperationHandler:\n If an ``operationId`` is missing from the spec or if no corresponding\n 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\n a corresponding ``APIRoute`` on the FastAPI application.\n - Injects FastAPI ``Depends()`` for each security requirement found\n on the operation or inherited from the top-level ``security`` field.\n\n **Guarantees:**\n\n - Route registration is deterministic and spec-driven. No route\n decorators are required or supported. Handler resolution errors\n surface at application startup." }, "load_openapi": { "name": "load_openapi", @@ -64,7 +71,7 @@ "name": "OpenAPIFirstApp", "kind": "class", "path": "openapi_first.app.OpenAPIFirstApp", - "signature": "", + "signature": "", "docstring": "FastAPI application enforcing OpenAPI-first design.\n\nNotes:\n **Responsibilities:**\n\n - `OpenAPIFirstApp` subclasses `FastAPI` and replaces manual route\n registration with OpenAPI-driven binding.\n - All routes are derived from the provided OpenAPI specification,\n and each ``operationId`` is mapped to a Python function in the\n supplied routes module.\n - Auth dependencies are auto-injected from the spec's\n ``securitySchemes`` and per-operation ``security`` fields.\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 - Auth enforcement is driven entirely by the spec — no manual\n middleware or decorators required.\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": { @@ -75,13 +82,6 @@ "docstring": null } } - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "openapi_first.app.Any", - "signature": "", - "docstring": null } } }, @@ -118,7 +118,7 @@ "kind": "function", "path": "openapi_first.binder.bind_routes", "signature": "", - "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\n exactly match an OpenAPI `operationId`.\n security_deps (dict | None):\n Optional mapping of ``METHOD:/path`` → ``list[Depends(...)]``\n generated from the spec's ``securitySchemes`` and per-operation\n ``security`` fields.\n\nRaises:\n MissingOperationHandler:\n If an ``operationId`` is missing from the spec or if no corresponding\n 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\n a corresponding ``APIRoute`` on the FastAPI application.\n - Injects FastAPI ``Depends()`` for each security requirement found\n on the operation or inherited from the top-level ``security`` field.\n\n **Guarantees:**\n\n - Route registration is deterministic and spec-driven. No route\n decorators are required or supported. Handler resolution errors\n surface at application startup." + "docstring": "Bind OpenAPI operations to FastAPI routes.\n\nArgs:\n app (Any):\n The FastAPI application instance to which routes will be added.\n spec (dict):\n Parsed OpenAPI 3.x specification dictionary.\n routes_module (Any):\n Python module containing handler functions. Each handler's name MUST\n exactly match an OpenAPI `operationId`.\n security_deps (dict[str, list[Any]] | None):\n Optional mapping of ``METHOD:/path`` → ``list[Depends(...)]``\n generated from the spec's ``securitySchemes`` and per-operation\n ``security`` fields.\n\nRaises:\n MissingOperationHandler:\n If an ``operationId`` is missing from the spec or if no corresponding\n 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\n a corresponding ``APIRoute`` on the FastAPI application.\n - Injects FastAPI ``Depends()`` for each security requirement found\n on the operation or inherited from the top-level ``security`` field.\n\n **Guarantees:**\n\n - Route registration is deterministic and spec-driven. No route\n decorators are required or supported. Handler resolution errors\n surface at application startup." }, "FastAPI": { "name": "FastAPI", @@ -134,7 +134,7 @@ "kind": "module", "path": "openapi_first.cli", "signature": null, - "docstring": "Command-line interface for FastAPI OpenAPI-first scaffolding utilities.\n\n---\n\n## Summary\n\nThis CLI bootstraps OpenAPI-first FastAPI applications from versioned,\nbundled templates packaged with the library.", + "docstring": "# Summary\n\nCommand-line interface for FastAPI OpenAPI-first scaffolding utilities.\n\nThis CLI bootstraps OpenAPI-first FastAPI applications from versioned,\nbundled templates packaged with the library.", "members": { "argparse": { "name": "argparse", @@ -175,21 +175,21 @@ "name": "available_templates", "kind": "function", "path": "openapi_first.cli.available_templates", - "signature": "", + "signature": "", "docstring": "Return a list of available application templates.\n\nReturns:\n list[str]:\n Sorted list of template names found in the internal templates directory." }, "copy_template": { "name": "copy_template", "kind": "function", "path": "openapi_first.cli.copy_template", - "signature": "", + "signature": "", "docstring": "Copy a bundled OpenAPI-first application template into a directory.\n\nArgs:\n template (str):\n Name of the template to copy.\n target_dir (Path):\n Filesystem path where the template should be copied.\n\nRaises:\n FileNotFoundError:\n If the requested template does not exist." }, "main": { "name": "main", "kind": "function", "path": "openapi_first.cli.main", - "signature": "", + "signature": "", "docstring": null } } @@ -322,7 +322,7 @@ "kind": "function", "path": "openapi_first.codegen.generate_routes", "signature": "", - "docstring": "Generate route handler stubs from an OpenAPI specification.\n\nCreates one ``.py`` file per resource in *output_dir*.\nResources are derived from the first path segment (e.g. ``/pets``\nand ``/pets/{id}`` both group under ``pets``).\n\nArgs:\n spec_path:\n Path to the OpenAPI specification file (YAML or JSON).\n output_dir:\n Directory where the generated route files are written.\n Created automatically if it does not exist.\n use_models:\n If ``True``, import Pydantic models from *models_module*\n for request-body schemas referenced via ``$ref``.\n models_module:\n Dotted Python module path from which to import models\n (e.g. ``\"models\"``, ``\"app.models\"``).\n\nReturns:\n list[Path]:\n Absolute paths of every generated route file.\n\nRaises:\n OpenAPISpecLoadError:\n If the spec cannot be loaded or validated.\n ValueError:\n If any operation is missing ``operationId``." + "docstring": "Generate route handler stubs from an OpenAPI specification.\n\nCreates one ``.py`` file per resource in *output_dir*.\nResources are derived from the first path segment (e.g. ``/pets``\nand ``/pets/{id}`` both group under ``pets``).\n\nArgs:\n spec_path (Path):\n Path to the OpenAPI specification file (YAML or JSON).\n output_dir (Path):\n Directory where the generated route files are written.\n Created automatically if it does not exist.\n use_models (bool, optional):\n If ``True``, import Pydantic models from *models_module*\n for request-body schemas referenced via ``$ref``.\n models_module (str, optional):\n Dotted Python module path from which to import models\n (e.g. ``\"models\"``, ``\"app.models\"``).\n\nReturns:\n list[Path]:\n Absolute paths of every generated route file.\n\nRaises:\n OpenAPISpecLoadError:\n If the spec cannot be loaded or validated.\n ValueError:\n If any operation is missing ``operationId``." }, "generate_models": { "name": "generate_models", @@ -338,7 +338,7 @@ "kind": "module", "path": "openapi_first.codegen_routes", "signature": null, - "docstring": "Route handler code generation from OpenAPI specifications.\n\nThis module generates Python route handler stubs from an OpenAPI 3.x\nspecification. Each resource (derived from the first path segment)\ngets its own file under the output directory. Every OpenAPI operation\nmust define an ``operationId``, which becomes the handler function name.\n\nNotes:\n **Design constraints:**\n\n - ``operationId`` is required on every operation (matching\n ``binder.bind_routes``).\n - Handlers are stubs raising ``NotImplementedError``.\n - Sub-resources (e.g. ``/pets/{id}/photo``) are grouped with their\n parent resource (``pets``).\n - Parameter types and defaults are inferred from the spec.\n - ``response: Response`` is injected for non-200 success codes.", + "docstring": "# Summary\n\nRoute handler code generation from OpenAPI specifications.\n\nThis module generates Python route handler stubs from an OpenAPI 3.x\nspecification. Each resource (derived from the first path segment)\ngets its own file under the output directory. Every OpenAPI operation\nmust define an ``operationId``, which becomes the handler function name.\n\nNotes:\n **Design constraints:**\n\n - ``operationId`` is required on every operation (matching\n ``binder.bind_routes``).\n - Handlers are stubs raising ``NotImplementedError``.\n - Sub-resources (e.g. ``/pets/{id}/photo``) are grouped with their\n parent resource (``pets``).\n - Parameter types and defaults are inferred from the spec.\n - ``response: Response`` is injected for non-200 success codes.", "members": { "Path": { "name": "Path", @@ -365,8 +365,8 @@ "name": "generate_routes", "kind": "function", "path": "openapi_first.codegen_routes.generate_routes", - "signature": "", - "docstring": "Generate route handler stubs from an OpenAPI specification.\n\nCreates one ``.py`` file per resource in *output_dir*.\nResources are derived from the first path segment (e.g. ``/pets``\nand ``/pets/{id}`` both group under ``pets``).\n\nArgs:\n spec_path:\n Path to the OpenAPI specification file (YAML or JSON).\n output_dir:\n Directory where the generated route files are written.\n Created automatically if it does not exist.\n use_models:\n If ``True``, import Pydantic models from *models_module*\n for request-body schemas referenced via ``$ref``.\n models_module:\n Dotted Python module path from which to import models\n (e.g. ``\"models\"``, ``\"app.models\"``).\n\nReturns:\n list[Path]:\n Absolute paths of every generated route file.\n\nRaises:\n OpenAPISpecLoadError:\n If the spec cannot be loaded or validated.\n ValueError:\n If any operation is missing ``operationId``." + "signature": "", + "docstring": "Generate route handler stubs from an OpenAPI specification.\n\nCreates one ``.py`` file per resource in *output_dir*.\nResources are derived from the first path segment (e.g. ``/pets``\nand ``/pets/{id}`` both group under ``pets``).\n\nArgs:\n spec_path (Path):\n Path to the OpenAPI specification file (YAML or JSON).\n output_dir (Path):\n Directory where the generated route files are written.\n Created automatically if it does not exist.\n use_models (bool, optional):\n If ``True``, import Pydantic models from *models_module*\n for request-body schemas referenced via ``$ref``.\n models_module (str, optional):\n Dotted Python module path from which to import models\n (e.g. ``\"models\"``, ``\"app.models\"``).\n\nReturns:\n list[Path]:\n Absolute paths of every generated route file.\n\nRaises:\n OpenAPISpecLoadError:\n If the spec cannot be loaded or validated.\n ValueError:\n If any operation is missing ``operationId``." } } }, @@ -463,7 +463,7 @@ "kind": "module", "path": "openapi_first.security", "signature": null, - "docstring": "OpenAPI security scheme parsing and auto-generated auth dependencies.\n\nReads `securitySchemes` and per-operation `security` from an OpenAPI spec,\nresolves `{ENV_VAR}` placeholders in `x-` extension fields, and generates\nFastAPI dependencies for token validation (e.g., Bearer JWT introspection).", + "docstring": "# Summary\n\nOpenAPI security scheme parsing and auto-generated auth dependencies.\n\nThis module reads `securitySchemes` and per-operation `security` from an\nOpenAPI spec, resolves `{ENV_VAR}` placeholders in `x-` extension fields,\nand generates FastAPI dependencies for token validation (e.g., Bearer JWT\nintrospection).", "members": { "os": { "name": "os", @@ -539,14 +539,14 @@ "name": "parse_security_schemes", "kind": "function", "path": "openapi_first.security.parse_security_schemes", - "signature": "", + "signature": "", "docstring": "Extract and resolve environment variables in security schemes." }, "make_security_dependencies": { "name": "make_security_dependencies", "kind": "function", "path": "openapi_first.security.make_security_dependencies", - "signature": "", + "signature": "", "docstring": "Build a mapping of ``METHOD:/path`` → list of ``Depends(...)``.\n\nThe effective security for each operation is resolved by:\n\n1. Using the operation-level ``security`` field if present.\n2. Falling back to the top-level ``security`` field.\n3. An empty list means *no auth required* for that operation." } } diff --git a/docs/mcp/modules/openapi_first.security.json b/docs/mcp/modules/openapi_first.security.json index ac2fd9e..f8f812d 100644 --- a/docs/mcp/modules/openapi_first.security.json +++ b/docs/mcp/modules/openapi_first.security.json @@ -2,7 +2,7 @@ "module": "openapi_first.security", "content": { "path": "openapi_first.security", - "docstring": "OpenAPI security scheme parsing and auto-generated auth dependencies.\n\nReads `securitySchemes` and per-operation `security` from an OpenAPI spec,\nresolves `{ENV_VAR}` placeholders in `x-` extension fields, and generates\nFastAPI dependencies for token validation (e.g., Bearer JWT introspection).", + "docstring": "# Summary\n\nOpenAPI security scheme parsing and auto-generated auth dependencies.\n\nThis module reads `securitySchemes` and per-operation `security` from an\nOpenAPI spec, resolves `{ENV_VAR}` placeholders in `x-` extension fields,\nand generates FastAPI dependencies for token validation (e.g., Bearer JWT\nintrospection).", "objects": { "os": { "name": "os", @@ -78,14 +78,14 @@ "name": "parse_security_schemes", "kind": "function", "path": "openapi_first.security.parse_security_schemes", - "signature": "", + "signature": "", "docstring": "Extract and resolve environment variables in security schemes." }, "make_security_dependencies": { "name": "make_security_dependencies", "kind": "function", "path": "openapi_first.security.make_security_dependencies", - "signature": "", + "signature": "", "docstring": "Build a mapping of ``METHOD:/path`` → list of ``Depends(...)``.\n\nThe effective security for each operation is resolved by:\n\n1. Using the operation-level ``security`` field if present.\n2. Falling back to the top-level ``security`` field.\n3. An empty list means *no auth required* for that operation." } } diff --git a/docs/mcp/nav.json b/docs/mcp/nav.json index 0299586..1d3595f 100644 --- a/docs/mcp/nav.json +++ b/docs/mcp/nav.json @@ -1,130 +1,130 @@ [ { "module": "openapi_first", - "resource": "doc://modules/openapi_first" + "resource": "docs://modules/openapi_first" }, { "module": "openapi_first.app", - "resource": "doc://modules/openapi_first.app" + "resource": "docs://modules/openapi_first.app" }, { "module": "openapi_first.binder", - "resource": "doc://modules/openapi_first.binder" + "resource": "docs://modules/openapi_first.binder" }, { "module": "openapi_first.cli", - "resource": "doc://modules/openapi_first.cli" + "resource": "docs://modules/openapi_first.cli" }, { "module": "openapi_first.client", - "resource": "doc://modules/openapi_first.client" + "resource": "docs://modules/openapi_first.client" }, { "module": "openapi_first.codegen", - "resource": "doc://modules/openapi_first.codegen" + "resource": "docs://modules/openapi_first.codegen" }, { "module": "openapi_first.codegen_routes", - "resource": "doc://modules/openapi_first.codegen_routes" + "resource": "docs://modules/openapi_first.codegen_routes" }, { "module": "openapi_first.errors", - "resource": "doc://modules/openapi_first.errors" + "resource": "docs://modules/openapi_first.errors" }, { "module": "openapi_first.loader", - "resource": "doc://modules/openapi_first.loader" + "resource": "docs://modules/openapi_first.loader" }, { "module": "openapi_first.security", - "resource": "doc://modules/openapi_first.security" + "resource": "docs://modules/openapi_first.security" }, { "module": "openapi_first.templates", - "resource": "doc://modules/openapi_first.templates" + "resource": "docs://modules/openapi_first.templates" }, { "module": "openapi_first.templates.crud_app", - "resource": "doc://modules/openapi_first.templates.crud_app" + "resource": "docs://modules/openapi_first.templates.crud_app" }, { "module": "openapi_first.templates.crud_app.data", - "resource": "doc://modules/openapi_first.templates.crud_app.data" + "resource": "docs://modules/openapi_first.templates.crud_app.data" }, { "module": "openapi_first.templates.crud_app.main", - "resource": "doc://modules/openapi_first.templates.crud_app.main" + "resource": "docs://modules/openapi_first.templates.crud_app.main" }, { "module": "openapi_first.templates.crud_app.routes", - "resource": "doc://modules/openapi_first.templates.crud_app.routes" + "resource": "docs://modules/openapi_first.templates.crud_app.routes" }, { "module": "openapi_first.templates.crud_app.test_crud_app", - "resource": "doc://modules/openapi_first.templates.crud_app.test_crud_app" + "resource": "docs://modules/openapi_first.templates.crud_app.test_crud_app" }, { "module": "openapi_first.templates.health_app", - "resource": "doc://modules/openapi_first.templates.health_app" + "resource": "docs://modules/openapi_first.templates.health_app" }, { "module": "openapi_first.templates.health_app.main", - "resource": "doc://modules/openapi_first.templates.health_app.main" + "resource": "docs://modules/openapi_first.templates.health_app.main" }, { "module": "openapi_first.templates.health_app.routes", - "resource": "doc://modules/openapi_first.templates.health_app.routes" + "resource": "docs://modules/openapi_first.templates.health_app.routes" }, { "module": "openapi_first.templates.model_app", - "resource": "doc://modules/openapi_first.templates.model_app" + "resource": "docs://modules/openapi_first.templates.model_app" }, { "module": "openapi_first.templates.model_app.data", - "resource": "doc://modules/openapi_first.templates.model_app.data" + "resource": "docs://modules/openapi_first.templates.model_app.data" }, { "module": "openapi_first.templates.model_app.main", - "resource": "doc://modules/openapi_first.templates.model_app.main" + "resource": "docs://modules/openapi_first.templates.model_app.main" }, { "module": "openapi_first.templates.model_app.models", - "resource": "doc://modules/openapi_first.templates.model_app.models" + "resource": "docs://modules/openapi_first.templates.model_app.models" }, { "module": "openapi_first.templates.model_app.routes", - "resource": "doc://modules/openapi_first.templates.model_app.routes" + "resource": "docs://modules/openapi_first.templates.model_app.routes" }, { "module": "openapi_first.templates.model_app.test_model_app", - "resource": "doc://modules/openapi_first.templates.model_app.test_model_app" + "resource": "docs://modules/openapi_first.templates.model_app.test_model_app" }, { "module": "openapi_first.templates.vet_app", - "resource": "doc://modules/openapi_first.templates.vet_app" + "resource": "docs://modules/openapi_first.templates.vet_app" }, { "module": "openapi_first.templates.vet_app.data", - "resource": "doc://modules/openapi_first.templates.vet_app.data" + "resource": "docs://modules/openapi_first.templates.vet_app.data" }, { "module": "openapi_first.templates.vet_app.main", - "resource": "doc://modules/openapi_first.templates.vet_app.main" + "resource": "docs://modules/openapi_first.templates.vet_app.main" }, { "module": "openapi_first.templates.vet_app.models", - "resource": "doc://modules/openapi_first.templates.vet_app.models" + "resource": "docs://modules/openapi_first.templates.vet_app.models" }, { "module": "openapi_first.templates.vet_app.routes", - "resource": "doc://modules/openapi_first.templates.vet_app.routes" + "resource": "docs://modules/openapi_first.templates.vet_app.routes" }, { "module": "openapi_first.templates.vet_app.sse", - "resource": "doc://modules/openapi_first.templates.vet_app.sse" + "resource": "docs://modules/openapi_first.templates.vet_app.sse" }, { "module": "openapi_first.templates.vet_app.test_vet_app", - "resource": "doc://modules/openapi_first.templates.vet_app.test_vet_app" + "resource": "docs://modules/openapi_first.templates.vet_app.test_vet_app" } ] \ No newline at end of file diff --git a/openapi_first/app.py b/openapi_first/app.py index ea0a70f..123f93e 100644 --- a/openapi_first/app.py +++ b/openapi_first/app.py @@ -34,6 +34,7 @@ Notes: import os import re +from typing import Any from fastapi import FastAPI @@ -105,8 +106,8 @@ class OpenAPIFirstApp(FastAPI): self, *, openapi_path: str, - routes_module, - **fastapi_kwargs, + routes_module: Any, + **fastapi_kwargs: Any, ): """ Initialize the application. @@ -115,7 +116,7 @@ class OpenAPIFirstApp(FastAPI): openapi_path (str): Filesystem path to the OpenAPI 3.x specification file. This specification is treated as the authoritative API contract. - routes_module (module): + routes_module (Any): Python module containing handler functions whose names correspond exactly to OpenAPI ``operationId`` values. **fastapi_kwargs (Any): diff --git a/openapi_first/binder.py b/openapi_first/binder.py index 590d3dd..6d3e293 100644 --- a/openapi_first/binder.py +++ b/openapi_first/binder.py @@ -40,23 +40,23 @@ from .errors import MissingOperationHandler def bind_routes( - app, + app: Any, spec: dict, - routes_module, + routes_module: Any, security_deps: dict[str, list[Any]] | None = None, ) -> None: """ Bind OpenAPI operations to FastAPI routes. Args: - app (fastapi.FastAPI): + app (Any): The FastAPI application instance to which routes will be added. spec (dict): Parsed OpenAPI 3.x specification dictionary. - routes_module (module): + routes_module (Any): Python module containing handler functions. Each handler's name MUST exactly match an OpenAPI `operationId`. - security_deps (dict | None): + security_deps (dict[str, list[Any]] | None): Optional mapping of ``METHOD:/path`` → ``list[Depends(...)]`` generated from the spec's ``securitySchemes`` and per-operation ``security`` fields. diff --git a/openapi_first/cli.py b/openapi_first/cli.py index 93bdb61..149ed4c 100644 --- a/openapi_first/cli.py +++ b/openapi_first/cli.py @@ -1,10 +1,8 @@ """ +# Summary + Command-line interface for FastAPI OpenAPI-first scaffolding utilities. ---- - -## Summary - This CLI bootstraps OpenAPI-first FastAPI applications from versioned, bundled templates packaged with the library. """ diff --git a/openapi_first/client.py b/openapi_first/client.py index 4355d50..0933cdc 100644 --- a/openapi_first/client.py +++ b/openapi_first/client.py @@ -98,9 +98,9 @@ class OpenAPIClient: Args: spec (dict[str, Any]): Parsed OpenAPI 3.x specification. - base_url (str, optional): + base_url (str | None): Base URL of the target service. If omitted, the first entry in the OpenAPI `servers` list is used. - client (httpx.Client, optional): + client (httpx.Client | None): Optional preconfigured httpx client instance. Raises: diff --git a/openapi_first/codegen_routes.py b/openapi_first/codegen_routes.py index ef8b742..577762c 100644 --- a/openapi_first/codegen_routes.py +++ b/openapi_first/codegen_routes.py @@ -1,4 +1,6 @@ """ +# Summary + Route handler code generation from OpenAPI specifications. This module generates Python route handler stubs from an OpenAPI 3.x @@ -39,15 +41,15 @@ def generate_routes( and ``/pets/{id}`` both group under ``pets``). Args: - spec_path: + spec_path (Path): Path to the OpenAPI specification file (YAML or JSON). - output_dir: + output_dir (Path): Directory where the generated route files are written. Created automatically if it does not exist. - use_models: + use_models (bool, optional): If ``True``, import Pydantic models from *models_module* for request-body schemas referenced via ``$ref``. - models_module: + models_module (str, optional): Dotted Python module path from which to import models (e.g. ``"models"``, ``"app.models"``). diff --git a/openapi_first/errors.py b/openapi_first/errors.py index a1ef51d..2857a9a 100644 --- a/openapi_first/errors.py +++ b/openapi_first/errors.py @@ -63,7 +63,7 @@ class MissingOperationHandler(OpenAPIFirstError): The HTTP path declared in the OpenAPI specification. method (str): The HTTP method (as declared in the OpenAPI spec). - operation_id (str, optional): + operation_id (str | None): The operationId declared in the OpenAPI spec, if present. """ if operation_id: diff --git a/openapi_first/security.py b/openapi_first/security.py index 4180785..7339474 100644 --- a/openapi_first/security.py +++ b/openapi_first/security.py @@ -1,9 +1,12 @@ """ +# Summary + OpenAPI security scheme parsing and auto-generated auth dependencies. -Reads `securitySchemes` and per-operation `security` from an OpenAPI spec, -resolves `{ENV_VAR}` placeholders in `x-` extension fields, and generates -FastAPI dependencies for token validation (e.g., Bearer JWT introspection). +This module reads `securitySchemes` and per-operation `security` from an +OpenAPI spec, resolves `{ENV_VAR}` placeholders in `x-` extension fields, +and generates FastAPI dependencies for token validation (e.g., Bearer JWT +introspection). """ import os