From 80f8defcc27d7374fd697c0e0d0372071917c397 Mon Sep 17 00:00:00 2001 From: Vishesh 'ironeagle' Bangotra Date: Sun, 8 Mar 2026 00:41:19 +0530 Subject: [PATCH] mcp docs --- docs/index.md | 1 + mcp_docs/modules/openapi_first.app.json | 10 +-- mcp_docs/modules/openapi_first.binder.json | 8 +- mcp_docs/modules/openapi_first.cli.json | 12 +-- mcp_docs/modules/openapi_first.client.json | 12 +-- mcp_docs/modules/openapi_first.errors.json | 10 +-- mcp_docs/modules/openapi_first.json | 80 +++++++++---------- mcp_docs/modules/openapi_first.loader.json | 12 +-- .../openapi_first.templates.crud_app.json | 6 +- ...openapi_first.templates.crud_app.main.json | 2 +- ...irst.templates.crud_app.test_crud_app.json | 4 +- .../openapi_first.templates.health_app.json | 2 +- ...enapi_first.templates.health_app.main.json | 2 +- mcp_docs/modules/openapi_first.templates.json | 14 ++-- .../openapi_first.templates.model_app.json | 6 +- ...penapi_first.templates.model_app.main.json | 2 +- ...st.templates.model_app.test_model_app.json | 4 +- mkdocs.yml | 33 +++++++- 18 files changed, 126 insertions(+), 94 deletions(-) diff --git a/docs/index.md b/docs/index.md index ee4b379..767439d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,3 +1,4 @@ # openapi_first ::: openapi_first +- [Openapi First](openapi_first/) diff --git a/mcp_docs/modules/openapi_first.app.json b/mcp_docs/modules/openapi_first.app.json index fc36d93..07946f7 100644 --- a/mcp_docs/modules/openapi_first.app.json +++ b/mcp_docs/modules/openapi_first.app.json @@ -2,7 +2,7 @@ "module": "openapi_first.app", "content": { "path": "openapi_first.app", - "docstring": "openapi_first.app\n=========================\n\nOpenAPI-first application bootstrap for FastAPI.\n\nThis module provides `OpenAPIFirstApp`, a thin but strict abstraction\nthat enforces OpenAPI as the single source of truth for a FastAPI service.\n\nCore 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\n 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\nWhat this module does\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\nWhat this module does NOT do\n----------------------------\n- It does not generate OpenAPI specs.\n- It does not generate client code.\n- It does not introduce a new framework or lifecycle.\n- It does not alter FastAPI dependency injection semantics.\n\nIntended usage\n--------------\nThis module is intended for teams that want:\n\n- OpenAPI-first API development\n- Strong contract enforcement\n- Minimal FastAPI boilerplate\n- Predictable, CI-friendly failures for spec/implementation drift", + "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", @@ -16,21 +16,21 @@ "kind": "function", "path": "openapi_first.app.load_openapi", "signature": "", - "docstring": "Load and validate an OpenAPI 3.x specification from disk.\n\nThe specification is parsed based on file extension and validated\nusing a strict OpenAPI schema validator. Any error results in an\nimmediate exception, preventing application startup.\n\nParameters\n----------\npath : str or pathlib.Path\n Filesystem path to an OpenAPI specification file.\n Supported extensions:\n - `.json`\n - `.yaml`\n - `.yml`\n\nReturns\n-------\ndict\n Parsed and validated OpenAPI specification.\n\nRaises\n------\nOpenAPISpecLoadError\n If the file does not exist, cannot be parsed, or fails\n OpenAPI schema validation." + "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": "", - "docstring": "Bind OpenAPI operations to FastAPI routes.\n\nIterates through the OpenAPI specification paths and methods,\nresolves each operationId to a handler function, and registers\na corresponding APIRoute on the FastAPI application.\n\nParameters\n----------\napp : fastapi.FastAPI\n The FastAPI application instance to which routes will be added.\n\nspec : dict\n Parsed OpenAPI 3.x specification dictionary.\n\nroutes_module : module\n Python module containing handler functions. Each handler's\n name MUST exactly match an OpenAPI operationId.\n\nRaises\n------\nMissingOperationHandler\n If an operationId is missing from the spec or if no corresponding\n handler function exists in the routes module.\n\nBehavior guarantees\n-------------------\n- Route registration is deterministic and spec-driven.\n- No route decorators are required or supported.\n- Handler resolution errors surface at application startup." + "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": "", - "docstring": "FastAPI application enforcing OpenAPI-first design.\n\n`OpenAPIFirstApp` subclasses FastAPI and replaces manual route\nregistration with OpenAPI-driven binding. All routes are derived\nfrom the provided OpenAPI specification, and each operationId is\nmapped to a Python function in the supplied routes module.\n\nParameters\n----------\nopenapi_path : str\n Filesystem path to the OpenAPI 3.x specification file.\n This specification is treated as the authoritative API contract.\n\nroutes_module : module\n Python module containing handler functions whose names correspond\n exactly to OpenAPI operationId values.\n\n**fastapi_kwargs\n Additional keyword arguments passed directly to `fastapi.FastAPI`\n (e.g., title, version, middleware, lifespan handlers).\n\nRaises\n------\nOpenAPIFirstError\n If the OpenAPI specification is invalid, or if any declared\n operationId does not have a corresponding handler function.\n\nBehavior 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-------\n```python\nfrom openapi_first import OpenAPIFirstApp\nimport app.routes as routes\n\napp = OpenAPIFirstApp(\n openapi_path=\"app/openapi.json\",\n routes_module=routes,\n title=\"Example Service\",\n)\n```", + "signature": "", + "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", diff --git a/mcp_docs/modules/openapi_first.binder.json b/mcp_docs/modules/openapi_first.binder.json index c2bdc4d..d5efd5f 100644 --- a/mcp_docs/modules/openapi_first.binder.json +++ b/mcp_docs/modules/openapi_first.binder.json @@ -2,7 +2,7 @@ "module": "openapi_first.binder", "content": { "path": "openapi_first.binder", - "docstring": "openapi_first.binder\n============================\n\nOpenAPI-driven route binding for FastAPI.\n\nThis module is responsible for translating an OpenAPI 3.x specification\ninto concrete FastAPI routes. It enforces a strict one-to-one mapping\nbetween OpenAPI operations and Python handler functions using operationId.\n\nCore responsibility\n-------------------\n- Read path + method definitions from an OpenAPI specification\n- Resolve each operationId to a Python callable\n- Register routes with FastAPI using APIRoute\n- Fail fast when contract violations are detected\n\nDesign constraints\n------------------\n- All routes MUST be declared in the OpenAPI specification.\n- All OpenAPI operations MUST define an operationId.\n- Every operationId MUST resolve to a handler function.\n- Handlers are plain Python callables (no decorators required).\n- No implicit route creation or inference is allowed.\n\nThis module intentionally does NOT:\n-------------------------------\n- Perform request or response validation\n- Generate Pydantic models\n- Modify FastAPI dependency injection\n- Interpret OpenAPI semantics beyond routing metadata\n\nThose concerns belong to other layers or tooling.", + "docstring": "OpenAPI-driven route binding for FastAPI.\n\n---\n\n## Summary\n\nThis module is responsible for translating an OpenAPI 3.x specification\ninto concrete FastAPI routes. It enforces a strict one-to-one mapping\nbetween OpenAPI operations and Python handler functions using operationId.\n\nNotes:\n **Core Responsibility:**\n\n - Read path + method definitions from an OpenAPI specification\n - Resolve each operationId to a Python callable\n - Register routes with FastAPI using APIRoute\n - Fail fast when contract violations are detected\n\n **Design Constraints:**\n\n - All routes MUST be declared in the OpenAPI specification\n - All OpenAPI operations MUST define an operationId\n - Every operationId MUST resolve to a handler function\n - Handlers are plain Python callables (no decorators required)\n - No implicit route creation or inference is allowed\n\n **Constraints:**\n\n - This module intentionally does NOT: Perform request or response validation, generate Pydantic models, modify FastAPI dependency injection, or interpret OpenAPI semantics beyond routing metadata.", "objects": { "APIRoute": { "name": "APIRoute", @@ -16,14 +16,14 @@ "kind": "class", "path": "openapi_first.binder.MissingOperationHandler", "signature": "", - "docstring": "Raised when an OpenAPI operation cannot be resolved to a handler.\n\nThis error occurs when:\n- An OpenAPI operation does not define an operationId, or\n- An operationId is defined but no matching function exists in the\n provided routes module.\n\nThis represents a violation of the OpenAPI-first contract and\nindicates that the specification and implementation are out of sync." + "docstring": "Raised when an OpenAPI operation cannot be resolved to a handler.\n\nNotes:\n **Scenarios:**\n\n - An OpenAPI operation does not define an operationId\n - An operationId is defined but no matching function exists in the provided routes module\n\n **Guarantees:**\n\n - This represents a violation of the OpenAPI-first contract and indicates that the specification and implementation are out of sync" }, "bind_routes": { "name": "bind_routes", "kind": "function", "path": "openapi_first.binder.bind_routes", - "signature": "", - "docstring": "Bind OpenAPI operations to FastAPI routes.\n\nIterates through the OpenAPI specification paths and methods,\nresolves each operationId to a handler function, and registers\na corresponding APIRoute on the FastAPI application.\n\nParameters\n----------\napp : fastapi.FastAPI\n The FastAPI application instance to which routes will be added.\n\nspec : dict\n Parsed OpenAPI 3.x specification dictionary.\n\nroutes_module : module\n Python module containing handler functions. Each handler's\n name MUST exactly match an OpenAPI operationId.\n\nRaises\n------\nMissingOperationHandler\n If an operationId is missing from the spec or if no corresponding\n handler function exists in the routes module.\n\nBehavior guarantees\n-------------------\n- Route registration is deterministic and spec-driven.\n- No route decorators are required or supported.\n- Handler resolution errors surface at application startup." + "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 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." }, "Any": { "name": "Any", diff --git a/mcp_docs/modules/openapi_first.cli.json b/mcp_docs/modules/openapi_first.cli.json index 2ca4689..ae4e103 100644 --- a/mcp_docs/modules/openapi_first.cli.json +++ b/mcp_docs/modules/openapi_first.cli.json @@ -2,7 +2,7 @@ "module": "openapi_first.cli", "content": { "path": "openapi_first.cli", - "docstring": "openapi_first.cli\n========================\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.", + "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.", "objects": { "argparse": { "name": "argparse", @@ -43,21 +43,21 @@ "name": "available_templates", "kind": "function", "path": "openapi_first.cli.available_templates", - "signature": "", - "docstring": "Return a list of available application templates." + "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": "", - "docstring": "Copy a bundled OpenAPI-first application template into a directory." + "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/mcp_docs/modules/openapi_first.client.json b/mcp_docs/modules/openapi_first.client.json index 9edf905..fe48f58 100644 --- a/mcp_docs/modules/openapi_first.client.json +++ b/mcp_docs/modules/openapi_first.client.json @@ -2,7 +2,7 @@ "module": "openapi_first.client", "content": { "path": "openapi_first.client", - "docstring": "openapi_first.client\n====================\n\nOpenAPI-first HTTP client for contract-driven services.\n\nThis module provides `OpenAPIClient`, a thin, strict HTTP client that\nderives all callable operations directly from an OpenAPI 3.x specification.\n\nIt is the client counterpart to `OpenAPIFirstApp`.\n\nCore principles\n---------------\n- The OpenAPI specification is the single source of truth.\n- Each operationId becomes a callable Python method.\n- No implicit schema mutation or inference.\n- No code generation step.\n- Minimal abstraction over httpx.\n\nWhat this module does\n---------------------\n- Parses an OpenAPI 3.x specification.\n- Dynamically creates one callable per operationId.\n- Enforces presence of:\n - servers\n - paths\n - operationId\n- Formats path parameters safely.\n- Handles JSON request bodies explicitly.\n- Returns raw `httpx.Response` objects.\n\nWhat this module does NOT do\n----------------------------\n- It does not generate client code.\n- It does not validate request/response schemas.\n- It does not deserialize responses.\n- It does not retry requests.\n- It does not implement authentication helpers.\n- It does not assume non-2xx responses are failures.\n\nIntended usage\n--------------\nThis client is designed for:\n\n- Service-to-service communication\n- Integration testing\n- Contract-driven internal SDK usage\n- Systems that want OpenAPI-first symmetry with `OpenAPIFirstApp`\n\nDesign constraints\n------------------\n- Only the first server in the OpenAPI `servers` list is used if\n `base_url` is not explicitly provided.\n- Only explicitly declared request bodies are allowed.\n- `application/json` is handled natively; other media types are sent as raw content.\n- All responses are returned as-is.", + "docstring": "OpenAPI-first HTTP client for contract-driven services.\n\n---\n\n## Summary\n\nThis module provides `OpenAPIClient`, a thin, strict HTTP client that\nderives all callable operations directly from an OpenAPI 3.x specification.\n\nIt is the client counterpart to `OpenAPIFirstApp`.\n\nNotes:\n **Core Principles:**\n\n - The OpenAPI specification is the single source of truth\n - Each operationId becomes a callable Python method\n - No implicit schema mutation or inference\n - No code generation step\n - Minimal abstraction over httpx\n\n **Responsibilities:**\n\n - Parses an OpenAPI 3.x specification\n - Dynamically creates one callable per operationId\n - Enforces presence of servers, paths, and operationId\n - Formats path parameters safely\n - Handles JSON request bodies explicitly\n - Returns raw `httpx.Response` objects\n\n **Constraints:**\n\n - This module intentionally does NOT: Generate client code, validate request/response schemas, deserialize responses, retry requests, implement authentication helpers, or assume non-2xx responses are failures.", "objects": { "Any": { "name": "Any", @@ -51,21 +51,21 @@ "kind": "class", "path": "openapi_first.client.OpenAPIFirstError", "signature": "", - "docstring": "Base exception for all OpenAPI-first enforcement errors.\n\nThis exception exists to allow callers, test suites, and CI pipelines\nto catch and distinguish OpenAPI contract violations from unrelated\nruntime errors.\n\nAll exceptions raised by the OpenAPI-first core should inherit from\nthis type." + "docstring": "Base exception for all OpenAPI-first enforcement errors.\n\nNotes:\n **Responsibilities:**\n\n - This exception exists to allow callers, test suites, and CI pipelines to catch and distinguish OpenAPI contract violations from unrelated runtime errors\n - All exceptions raised by the OpenAPI-first core should inherit from this type" }, "OpenAPIClientError": { "name": "OpenAPIClientError", "kind": "class", "path": "openapi_first.client.OpenAPIClientError", - "signature": "", + "signature": "", "docstring": "Raised when an OpenAPI client operation fails." }, "OpenAPIClient": { "name": "OpenAPIClient", "kind": "class", "path": "openapi_first.client.OpenAPIClient", - "signature": "", - "docstring": "OpenAPI-first HTTP client (httpx-based).\n\nThis client derives all callable methods directly from an OpenAPI 3.x\nspecification. Each operationId becomes a method on the client\ninstance.\n\nDesign principles\n-----------------\n- One callable per operationId\n- Explicit parameters (path, query, headers, body)\n- No implicit schema inference or mutation\n- Returns raw httpx.Response objects\n- No response validation or deserialization\n\nParameters\n----------\nspec : dict\n Parsed OpenAPI 3.x specification.\nbase_url : str | None\n Base URL of the target service. If omitted, the first entry\n in the OpenAPI `servers` list is used.\nclient : httpx.Client | None\n Optional preconfigured httpx client instance.\n\nRaises\n------\nOpenAPIClientError\n If:\n - No servers are defined and base_url is not provided\n - OpenAPI spec has no paths\n - An operation is missing operationId\n - Duplicate operationIds are detected\n - Required path parameters are missing\n - Required request body is missing\n\n Example\n-------\n```python\nfrom openapi_first import loader, client\n\nspec = loader.load_openapi(\"openapi.yaml\")\n\napi = client.OpenAPIClient(\n spec=spec,\n base_url=\"http://localhost:8000\",\n)\n\n# Call operationId: getUser\nresponse = api.getUser(\n path_params={\"user_id\": 123}\n)\n\nprint(response.status_code)\nprint(response.json())\n\n# Call operationId: createUser\nresponse = api.createUser(\n body={\"name\": \"Bob\"}\n)\n\nprint(response.status_code)\n```", + "signature": "", + "docstring": "OpenAPI-first HTTP client (httpx-based).\n\nNotes:\n **Responsibilities:**\n\n - This client derives all callable methods directly from an OpenAPI 3.x specification. Each operationId becomes a method on the client instance.\n\n **Guarantees:**\n\n - One callable per operationId\n - Explicit parameters (path, query, headers, body)\n - No implicit schema inference or mutation\n - Returns raw `httpx.Response` objects\n - No response validation or deserialization\n\nExample:\n ```python\n from openapi_first import loader, client\n\n spec = loader.load_openapi(\"openapi.yaml\")\n\n api = client.OpenAPIClient(\n spec=spec,\n base_url=\"http://localhost:8000\",\n )\n\n # Call operationId: getUser\n response = api.getUser(\n path_params={\"user_id\": 123}\n )\n\n print(response.status_code)\n print(response.json())\n ```", "members": { "spec": { "name": "spec", @@ -92,7 +92,7 @@ "name": "operations", "kind": "function", "path": "openapi_first.client.OpenAPIClient.operations", - "signature": "", + "signature": "", "docstring": null } } diff --git a/mcp_docs/modules/openapi_first.errors.json b/mcp_docs/modules/openapi_first.errors.json index 2c235e6..6be8a22 100644 --- a/mcp_docs/modules/openapi_first.errors.json +++ b/mcp_docs/modules/openapi_first.errors.json @@ -2,21 +2,21 @@ "module": "openapi_first.errors", "content": { "path": "openapi_first.errors", - "docstring": "openapi_first.errors\n============================\n\nCustom exceptions for OpenAPI-first FastAPI applications.\n\nThis module defines a small hierarchy of explicit, intention-revealing\nexceptions used to signal contract violations between an OpenAPI\nspecification and its Python implementation.\n\nDesign principles\n-----------------\n- Errors represent *programmer mistakes*, not runtime conditions.\n- All errors are raised during application startup.\n- Messages are actionable and suitable for CI/CD output.\n- Exceptions are explicit rather than reused from generic built-ins.\n\nThese errors should normally cause immediate application failure.", + "docstring": "Exceptions for OpenAPI-first FastAPI applications.\n\n---\n\n## Summary\n\nThis module defines a small hierarchy of explicit, intention-revealing\nexceptions used to signal contract violations between an OpenAPI\nspecification and its Python implementation.\n\nNotes:\n **Design Principles:**\n\n - Errors represent programmer mistakes, not runtime conditions\n - All errors are raised during application startup\n - Messages are actionable and suitable for CI/CD output\n - Exceptions are explicit rather than reused from generic built-ins\n\n These errors should normally cause immediate application failure.", "objects": { "OpenAPIFirstError": { "name": "OpenAPIFirstError", "kind": "class", "path": "openapi_first.errors.OpenAPIFirstError", - "signature": "", - "docstring": "Base exception for all OpenAPI-first enforcement errors.\n\nThis exception exists to allow callers, test suites, and CI pipelines\nto catch and distinguish OpenAPI contract violations from unrelated\nruntime errors.\n\nAll exceptions raised by the OpenAPI-first core should inherit from\nthis type." + "signature": "", + "docstring": "Base exception for all OpenAPI-first enforcement errors.\n\nNotes:\n **Responsibilities:**\n\n - This exception exists to allow callers, test suites, and CI pipelines to catch and distinguish OpenAPI contract violations from unrelated runtime errors\n - All exceptions raised by the OpenAPI-first core should inherit from this type" }, "MissingOperationHandler": { "name": "MissingOperationHandler", "kind": "class", "path": "openapi_first.errors.MissingOperationHandler", - "signature": "", - "docstring": "Raised when an OpenAPI operation cannot be resolved to a handler.\n\nThis error occurs when:\n- An OpenAPI operation does not define an operationId, or\n- An operationId is defined but no matching function exists in the\n provided routes module.\n\nThis represents a violation of the OpenAPI-first contract and\nindicates that the specification and implementation are out of sync." + "signature": "", + "docstring": "Raised when an OpenAPI operation cannot be resolved to a handler.\n\nNotes:\n **Scenarios:**\n\n - An OpenAPI operation does not define an operationId\n - An operationId is defined but no matching function exists in the provided routes module\n\n **Guarantees:**\n\n - This represents a violation of the OpenAPI-first contract and indicates that the specification and implementation are out of sync" }, "Optional": { "name": "Optional", diff --git a/mcp_docs/modules/openapi_first.json b/mcp_docs/modules/openapi_first.json index dc6485e..1c970ee 100644 --- a/mcp_docs/modules/openapi_first.json +++ b/mcp_docs/modules/openapi_first.json @@ -2,14 +2,14 @@ "module": "openapi_first", "content": { "path": "openapi_first", - "docstring": "FastAPI OpenAPI First — strict OpenAPI-first application bootstrap for FastAPI.\n\nFastAPI OpenAPI First is a **contract-first infrastructure library** that\nenforces OpenAPI as the single source of truth for FastAPI services.\n\nThe library removes decorator-driven routing and replaces it with\ndeterministic, spec-driven application assembly. Every HTTP route,\nmethod, and operation is defined in OpenAPI first and bound to Python\nhandlers explicitly via operationId.\n\nThe package is intentionally minimal and layered. Each module has a\nsingle responsibility and exposes explicit contracts rather than\nconvenience facades.\n\n----------------------------------------------------------------------\nArchitecture Overview\n----------------------------------------------------------------------\n\nThe library is structured around four core responsibilities:\n\n- loader: load and validate OpenAPI 3.x specifications (JSON/YAML)\n- binder: bind OpenAPI operations to FastAPI routes via operationId\n- app: OpenAPI-first FastAPI application bootstrap\n- client: OpenAPI-first HTTP client driven by the same specification\n- errors: explicit error hierarchy for contract violations\n\nThe package root acts as a **namespace**, not a facade. Consumers are\nexpected to import functionality explicitly from the appropriate module.\n\n----------------------------------------------------------------------\nInstallation\n----------------------------------------------------------------------\n\nInstall using pip:\n\n pip install openapi-first\n\nOr with Poetry:\n\n poetry add openapi-first\n\nRuntime dependencies are intentionally minimal:\n- fastapi (server-side)\n- httpx (client-side)\n- openapi-spec-validator\n- pyyaml (optional, for YAML specs)\n\nThe ASGI server (e.g., uvicorn) is an application-level dependency and is\nnot bundled with this library.\n\n----------------------------------------------------------------------\nCommand-Line Interface (Scaffolding, Templates)\n----------------------------------------------------------------------\n\nFastAPI OpenAPI First ships with a small CLI for bootstrapping\nOpenAPI-first FastAPI applications from bundled templates.\n\nList available application templates:\n\n openapi-first --list\n\nCreate a new application using the default template:\n\n openapi-first\n\nCreate a new application using a specific template:\n\n openapi-first health_app\n\nCreate a new application in a custom directory:\n\n openapi-first health_app my-service\n\nThe CLI copies template files verbatim into the target directory.\nNo code is generated or modified beyond the copied scaffold.\n\n----------------------------------------------------------------------\nServer-Side Usage (OpenAPI → FastAPI)\n----------------------------------------------------------------------\n\nMinimal OpenAPI-first FastAPI application:\n\n from openapi_first import app\n import my_service.routes as routes\n\n api = app.OpenAPIFirstApp(\n openapi_path=\"openapi.yaml\",\n routes_module=routes,\n title=\"My Service\",\n version=\"1.0.0\",\n )\n\n # Run with:\n # uvicorn my_service.main:api\n\nHandler definitions (no decorators):\n\n def get_health():\n return {\"status\": \"ok\"}\n\nOpenAPI snippet:\n\n paths:\n /health:\n get:\n operationId: get_health\n responses:\n \"200\":\n description: OK\n\nThe binder guarantees:\n- Every OpenAPI operationId has exactly one handler\n- No undocumented routes exist\n- All mismatches fail at application startup\n\n----------------------------------------------------------------------\nClient-Side Usage (OpenAPI → HTTP Client)\n----------------------------------------------------------------------\n\nThe same OpenAPI specification can be used to construct a strict,\noperationId-driven HTTP client.\n\nClient construction:\n\n from openapi_first.loader import load_openapi\n from openapi_first.client import OpenAPIClient\n\n spec = load_openapi(\"openapi.yaml\")\n\n client = OpenAPIClient(spec)\n\nCalling operations (operationId is the API):\n\n response = client.get_health()\n assert response.status_code == 200\n assert response.json() == {\"status\": \"ok\"}\n\nPath parameters must match the OpenAPI specification exactly:\n\n response = client.get_item(\n path_params={\"item_id\": 1}\n )\n\nRequest bodies are passed explicitly:\n\n response = client.create_item(\n body={\"name\": \"Orange\", \"price\": 0.8}\n )\n\nClient guarantees:\n- One callable per OpenAPI operationId\n- No hardcoded URLs or HTTP methods in user code\n- Path and body parameters must match the spec exactly\n- Invalid or incomplete OpenAPI specs fail at client construction time\n- No schema inference or mutation is performed\n\nThe client is transport-level only and returns `httpx.Response`\nobjects directly. Response interpretation and validation are left to\nthe consumer or higher-level layers.\n\n----------------------------------------------------------------------\nExtensibility Model\n----------------------------------------------------------------------\n\nFastAPI OpenAPI First is designed to be extended via **explicit contracts**:\n\n- Users MAY extend OpenAPI loading behavior (e.g. multi-file specs)\n by wrapping or replacing `loader.load_openapi`\n- Users MAY extend route binding behavior by building on top of\n `binder.bind_routes`\n- Users MAY layer additional validation (e.g. signature checks)\n without modifying core modules\n\nUsers SHOULD NOT rely on FastAPI decorators for routing when using this\nlibrary. Mixing decorator-driven routes with OpenAPI-first routing\ndefeats the contract guarantees and is explicitly unsupported.\n\n----------------------------------------------------------------------\nPublic API Surface\n----------------------------------------------------------------------\n\nThe supported public API consists of the following top-level modules:\n\n- openapi_first.app\n- openapi_first.binder\n- openapi_first.loader\n- openapi_first.client\n- openapi_first.errors\n\nClasses and functions should be imported explicitly from these modules.\nNo individual symbols are re-exported at the package root.\n\n----------------------------------------------------------------------\nDesign Guarantees\n----------------------------------------------------------------------\n\n- OpenAPI is the single source of truth\n- No undocumented routes can exist\n- No OpenAPI operation can exist without a handler or client callable\n- All contract violations fail at application startup or client creation\n- No hidden FastAPI magic or implicit behavior\n- Deterministic, testable application assembly\n- CI-friendly failure modes\n\nFastAPI OpenAPI First favors correctness, explicitness, and contract\nenforcement over convenience shortcuts.\n\n## Core Philosophy\n\n`FastAPI OpenAPI First` operates on the **Contract-as-Code** principle:\n\n1. **Spec-Driven Routing**: The OpenAPI document *is* the router. Code only exists to fulfill established contracts.\n2. **Startup Fail-Fast**: Binding mismatches (missing handlers or extra operations) are detected during app initialization, not at runtime.\n3. **Decoupled Symmetry**: The same specification drives both the FastAPI server and the `httpx`-based client, ensuring type-safe communication.\n\n## Documentation Design\n\nFollow these \"AI-Native\" docstring principles to maximize developer and agent productivity:\n\n### For Humans\n- **Logical Grouping**: Document the Loader, Binder, and Client as distinct infrastructure layers.\n- **Spec Snippets**: Always include the corresponding OpenAPI YAML/JSON snippet alongside Python examples.\n\n### For LLMs\n- **Full Path Linking**: Refer to cross-module dependencies using their full dotted paths (e.g., `openapi_first.loader.load_openapi`).\n- **Complete Stubs**: Maintain high-fidelity `.pyi` stubs for all public interfaces to provide an optimized machine-context.\n- **Traceable Errors**: Use specific `: description` pairs in `Raises` blocks to allow agents to accurately map errors to spec violations.", + "docstring": "FastAPI OpenAPI First — strict OpenAPI-first application bootstrap for FastAPI.\n\n---\n\n## Summary\n\nFastAPI OpenAPI First is a **contract-first infrastructure library** that\nenforces OpenAPI as the single source of truth for FastAPI services.\n\nThe library removes decorator-driven routing and replaces it with\ndeterministic, spec-driven application assembly. Every HTTP route,\nmethod, and operation is defined in OpenAPI first and bound to Python\nhandlers explicitly via operationId.\n\n---\n\n## Installation\n\nInstall using pip:\n\n pip install openapi-first\n\nOr with Poetry:\n\n poetry add openapi-first\n\n---\n\n## Quick start\n\nMinimal OpenAPI-first FastAPI application:\n\n from openapi_first import app\n import my_service.routes as routes\n\n api = app.OpenAPIFirstApp(\n openapi_path=\"openapi.yaml\",\n routes_module=routes,\n title=\"My Service\",\n version=\"1.0.0\",\n )\n\nOperationId-driven HTTP client:\n\n from openapi_first.loader import load_openapi\n from openapi_first.client import OpenAPIClient\n\n spec = load_openapi(\"openapi.yaml\")\n client = OpenAPIClient(spec)\n\n response = client.get_health()\n\n---\n\n## Architecture\n\nThe library is structured around four core responsibilities:\n\n- **loader**: Load and validate OpenAPI 3.x specifications (JSON/YAML)\n- **binder**: Bind OpenAPI operations to FastAPI routes via operationId\n- **app**: OpenAPI-first FastAPI application bootstrap\n- **client**: OpenAPI-first HTTP client driven by the same specification\n- **errors**: Explicit error hierarchy for contract violations\n\n---\n\n## Public API\n\nThe supported public API consists of the following top-level modules:\n\n- `openapi_first.app`\n- `openapi_first.binder`\n- `openapi_first.loader`\n- `openapi_first.client`\n- `openapi_first.errors`\n\n---\n\n## Design Guarantees\n\n- OpenAPI is the single source of truth\n- No undocumented routes can exist\n- No OpenAPI operation can exist without a handler or client callable\n- All contract violations fail at application startup or client creation\n- No hidden FastAPI magic or implicit behavior\n- Deterministic, testable application assembly\n\n---", "objects": { "app": { "name": "app", "kind": "module", "path": "openapi_first.app", "signature": null, - "docstring": "openapi_first.app\n=========================\n\nOpenAPI-first application bootstrap for FastAPI.\n\nThis module provides `OpenAPIFirstApp`, a thin but strict abstraction\nthat enforces OpenAPI as the single source of truth for a FastAPI service.\n\nCore 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\n 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\nWhat this module does\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\nWhat this module does NOT do\n----------------------------\n- It does not generate OpenAPI specs.\n- It does not generate client code.\n- It does not introduce a new framework or lifecycle.\n- It does not alter FastAPI dependency injection semantics.\n\nIntended usage\n--------------\nThis module is intended for teams that want:\n\n- OpenAPI-first API development\n- Strong contract enforcement\n- Minimal FastAPI boilerplate\n- Predictable, CI-friendly failures for spec/implementation drift", + "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.", "members": { "FastAPI": { "name": "FastAPI", @@ -23,21 +23,21 @@ "kind": "function", "path": "openapi_first.app.load_openapi", "signature": "", - "docstring": "Load and validate an OpenAPI 3.x specification from disk.\n\nThe specification is parsed based on file extension and validated\nusing a strict OpenAPI schema validator. Any error results in an\nimmediate exception, preventing application startup.\n\nParameters\n----------\npath : str or pathlib.Path\n Filesystem path to an OpenAPI specification file.\n Supported extensions:\n - `.json`\n - `.yaml`\n - `.yml`\n\nReturns\n-------\ndict\n Parsed and validated OpenAPI specification.\n\nRaises\n------\nOpenAPISpecLoadError\n If the file does not exist, cannot be parsed, or fails\n OpenAPI schema validation." + "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": "", - "docstring": "Bind OpenAPI operations to FastAPI routes.\n\nIterates through the OpenAPI specification paths and methods,\nresolves each operationId to a handler function, and registers\na corresponding APIRoute on the FastAPI application.\n\nParameters\n----------\napp : fastapi.FastAPI\n The FastAPI application instance to which routes will be added.\n\nspec : dict\n Parsed OpenAPI 3.x specification dictionary.\n\nroutes_module : module\n Python module containing handler functions. Each handler's\n name MUST exactly match an OpenAPI operationId.\n\nRaises\n------\nMissingOperationHandler\n If an operationId is missing from the spec or if no corresponding\n handler function exists in the routes module.\n\nBehavior guarantees\n-------------------\n- Route registration is deterministic and spec-driven.\n- No route decorators are required or supported.\n- Handler resolution errors surface at application startup." + "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": "", - "docstring": "FastAPI application enforcing OpenAPI-first design.\n\n`OpenAPIFirstApp` subclasses FastAPI and replaces manual route\nregistration with OpenAPI-driven binding. All routes are derived\nfrom the provided OpenAPI specification, and each operationId is\nmapped to a Python function in the supplied routes module.\n\nParameters\n----------\nopenapi_path : str\n Filesystem path to the OpenAPI 3.x specification file.\n This specification is treated as the authoritative API contract.\n\nroutes_module : module\n Python module containing handler functions whose names correspond\n exactly to OpenAPI operationId values.\n\n**fastapi_kwargs\n Additional keyword arguments passed directly to `fastapi.FastAPI`\n (e.g., title, version, middleware, lifespan handlers).\n\nRaises\n------\nOpenAPIFirstError\n If the OpenAPI specification is invalid, or if any declared\n operationId does not have a corresponding handler function.\n\nBehavior 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-------\n```python\nfrom openapi_first import OpenAPIFirstApp\nimport app.routes as routes\n\napp = OpenAPIFirstApp(\n openapi_path=\"app/openapi.json\",\n routes_module=routes,\n title=\"Example Service\",\n)\n```", + "signature": "", + "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", @@ -62,7 +62,7 @@ "kind": "module", "path": "openapi_first.binder", "signature": null, - "docstring": "openapi_first.binder\n============================\n\nOpenAPI-driven route binding for FastAPI.\n\nThis module is responsible for translating an OpenAPI 3.x specification\ninto concrete FastAPI routes. It enforces a strict one-to-one mapping\nbetween OpenAPI operations and Python handler functions using operationId.\n\nCore responsibility\n-------------------\n- Read path + method definitions from an OpenAPI specification\n- Resolve each operationId to a Python callable\n- Register routes with FastAPI using APIRoute\n- Fail fast when contract violations are detected\n\nDesign constraints\n------------------\n- All routes MUST be declared in the OpenAPI specification.\n- All OpenAPI operations MUST define an operationId.\n- Every operationId MUST resolve to a handler function.\n- Handlers are plain Python callables (no decorators required).\n- No implicit route creation or inference is allowed.\n\nThis module intentionally does NOT:\n-------------------------------\n- Perform request or response validation\n- Generate Pydantic models\n- Modify FastAPI dependency injection\n- Interpret OpenAPI semantics beyond routing metadata\n\nThose concerns belong to other layers or tooling.", + "docstring": "OpenAPI-driven route binding for FastAPI.\n\n---\n\n## Summary\n\nThis module is responsible for translating an OpenAPI 3.x specification\ninto concrete FastAPI routes. It enforces a strict one-to-one mapping\nbetween OpenAPI operations and Python handler functions using operationId.\n\nNotes:\n **Core Responsibility:**\n\n - Read path + method definitions from an OpenAPI specification\n - Resolve each operationId to a Python callable\n - Register routes with FastAPI using APIRoute\n - Fail fast when contract violations are detected\n\n **Design Constraints:**\n\n - All routes MUST be declared in the OpenAPI specification\n - All OpenAPI operations MUST define an operationId\n - Every operationId MUST resolve to a handler function\n - Handlers are plain Python callables (no decorators required)\n - No implicit route creation or inference is allowed\n\n **Constraints:**\n\n - This module intentionally does NOT: Perform request or response validation, generate Pydantic models, modify FastAPI dependency injection, or interpret OpenAPI semantics beyond routing metadata.", "members": { "APIRoute": { "name": "APIRoute", @@ -76,14 +76,14 @@ "kind": "class", "path": "openapi_first.binder.MissingOperationHandler", "signature": "", - "docstring": "Raised when an OpenAPI operation cannot be resolved to a handler.\n\nThis error occurs when:\n- An OpenAPI operation does not define an operationId, or\n- An operationId is defined but no matching function exists in the\n provided routes module.\n\nThis represents a violation of the OpenAPI-first contract and\nindicates that the specification and implementation are out of sync." + "docstring": "Raised when an OpenAPI operation cannot be resolved to a handler.\n\nNotes:\n **Scenarios:**\n\n - An OpenAPI operation does not define an operationId\n - An operationId is defined but no matching function exists in the provided routes module\n\n **Guarantees:**\n\n - This represents a violation of the OpenAPI-first contract and indicates that the specification and implementation are out of sync" }, "bind_routes": { "name": "bind_routes", "kind": "function", "path": "openapi_first.binder.bind_routes", - "signature": "", - "docstring": "Bind OpenAPI operations to FastAPI routes.\n\nIterates through the OpenAPI specification paths and methods,\nresolves each operationId to a handler function, and registers\na corresponding APIRoute on the FastAPI application.\n\nParameters\n----------\napp : fastapi.FastAPI\n The FastAPI application instance to which routes will be added.\n\nspec : dict\n Parsed OpenAPI 3.x specification dictionary.\n\nroutes_module : module\n Python module containing handler functions. Each handler's\n name MUST exactly match an OpenAPI operationId.\n\nRaises\n------\nMissingOperationHandler\n If an operationId is missing from the spec or if no corresponding\n handler function exists in the routes module.\n\nBehavior guarantees\n-------------------\n- Route registration is deterministic and spec-driven.\n- No route decorators are required or supported.\n- Handler resolution errors surface at application startup." + "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 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." }, "Any": { "name": "Any", @@ -113,7 +113,7 @@ "kind": "module", "path": "openapi_first.cli", "signature": null, - "docstring": "openapi_first.cli\n========================\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.", + "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.", "members": { "argparse": { "name": "argparse", @@ -154,21 +154,21 @@ "name": "available_templates", "kind": "function", "path": "openapi_first.cli.available_templates", - "signature": "", - "docstring": "Return a list of available application templates." + "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": "", - "docstring": "Copy a bundled OpenAPI-first application template into a directory." + "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 } } @@ -178,7 +178,7 @@ "kind": "module", "path": "openapi_first.client", "signature": null, - "docstring": "openapi_first.client\n====================\n\nOpenAPI-first HTTP client for contract-driven services.\n\nThis module provides `OpenAPIClient`, a thin, strict HTTP client that\nderives all callable operations directly from an OpenAPI 3.x specification.\n\nIt is the client counterpart to `OpenAPIFirstApp`.\n\nCore principles\n---------------\n- The OpenAPI specification is the single source of truth.\n- Each operationId becomes a callable Python method.\n- No implicit schema mutation or inference.\n- No code generation step.\n- Minimal abstraction over httpx.\n\nWhat this module does\n---------------------\n- Parses an OpenAPI 3.x specification.\n- Dynamically creates one callable per operationId.\n- Enforces presence of:\n - servers\n - paths\n - operationId\n- Formats path parameters safely.\n- Handles JSON request bodies explicitly.\n- Returns raw `httpx.Response` objects.\n\nWhat this module does NOT do\n----------------------------\n- It does not generate client code.\n- It does not validate request/response schemas.\n- It does not deserialize responses.\n- It does not retry requests.\n- It does not implement authentication helpers.\n- It does not assume non-2xx responses are failures.\n\nIntended usage\n--------------\nThis client is designed for:\n\n- Service-to-service communication\n- Integration testing\n- Contract-driven internal SDK usage\n- Systems that want OpenAPI-first symmetry with `OpenAPIFirstApp`\n\nDesign constraints\n------------------\n- Only the first server in the OpenAPI `servers` list is used if\n `base_url` is not explicitly provided.\n- Only explicitly declared request bodies are allowed.\n- `application/json` is handled natively; other media types are sent as raw content.\n- All responses are returned as-is.", + "docstring": "OpenAPI-first HTTP client for contract-driven services.\n\n---\n\n## Summary\n\nThis module provides `OpenAPIClient`, a thin, strict HTTP client that\nderives all callable operations directly from an OpenAPI 3.x specification.\n\nIt is the client counterpart to `OpenAPIFirstApp`.\n\nNotes:\n **Core Principles:**\n\n - The OpenAPI specification is the single source of truth\n - Each operationId becomes a callable Python method\n - No implicit schema mutation or inference\n - No code generation step\n - Minimal abstraction over httpx\n\n **Responsibilities:**\n\n - Parses an OpenAPI 3.x specification\n - Dynamically creates one callable per operationId\n - Enforces presence of servers, paths, and operationId\n - Formats path parameters safely\n - Handles JSON request bodies explicitly\n - Returns raw `httpx.Response` objects\n\n **Constraints:**\n\n - This module intentionally does NOT: Generate client code, validate request/response schemas, deserialize responses, retry requests, implement authentication helpers, or assume non-2xx responses are failures.", "members": { "Any": { "name": "Any", @@ -227,21 +227,21 @@ "kind": "class", "path": "openapi_first.client.OpenAPIFirstError", "signature": "", - "docstring": "Base exception for all OpenAPI-first enforcement errors.\n\nThis exception exists to allow callers, test suites, and CI pipelines\nto catch and distinguish OpenAPI contract violations from unrelated\nruntime errors.\n\nAll exceptions raised by the OpenAPI-first core should inherit from\nthis type." + "docstring": "Base exception for all OpenAPI-first enforcement errors.\n\nNotes:\n **Responsibilities:**\n\n - This exception exists to allow callers, test suites, and CI pipelines to catch and distinguish OpenAPI contract violations from unrelated runtime errors\n - All exceptions raised by the OpenAPI-first core should inherit from this type" }, "OpenAPIClientError": { "name": "OpenAPIClientError", "kind": "class", "path": "openapi_first.client.OpenAPIClientError", - "signature": "", + "signature": "", "docstring": "Raised when an OpenAPI client operation fails." }, "OpenAPIClient": { "name": "OpenAPIClient", "kind": "class", "path": "openapi_first.client.OpenAPIClient", - "signature": "", - "docstring": "OpenAPI-first HTTP client (httpx-based).\n\nThis client derives all callable methods directly from an OpenAPI 3.x\nspecification. Each operationId becomes a method on the client\ninstance.\n\nDesign principles\n-----------------\n- One callable per operationId\n- Explicit parameters (path, query, headers, body)\n- No implicit schema inference or mutation\n- Returns raw httpx.Response objects\n- No response validation or deserialization\n\nParameters\n----------\nspec : dict\n Parsed OpenAPI 3.x specification.\nbase_url : str | None\n Base URL of the target service. If omitted, the first entry\n in the OpenAPI `servers` list is used.\nclient : httpx.Client | None\n Optional preconfigured httpx client instance.\n\nRaises\n------\nOpenAPIClientError\n If:\n - No servers are defined and base_url is not provided\n - OpenAPI spec has no paths\n - An operation is missing operationId\n - Duplicate operationIds are detected\n - Required path parameters are missing\n - Required request body is missing\n\n Example\n-------\n```python\nfrom openapi_first import loader, client\n\nspec = loader.load_openapi(\"openapi.yaml\")\n\napi = client.OpenAPIClient(\n spec=spec,\n base_url=\"http://localhost:8000\",\n)\n\n# Call operationId: getUser\nresponse = api.getUser(\n path_params={\"user_id\": 123}\n)\n\nprint(response.status_code)\nprint(response.json())\n\n# Call operationId: createUser\nresponse = api.createUser(\n body={\"name\": \"Bob\"}\n)\n\nprint(response.status_code)\n```", + "signature": "", + "docstring": "OpenAPI-first HTTP client (httpx-based).\n\nNotes:\n **Responsibilities:**\n\n - This client derives all callable methods directly from an OpenAPI 3.x specification. Each operationId becomes a method on the client instance.\n\n **Guarantees:**\n\n - One callable per operationId\n - Explicit parameters (path, query, headers, body)\n - No implicit schema inference or mutation\n - Returns raw `httpx.Response` objects\n - No response validation or deserialization\n\nExample:\n ```python\n from openapi_first import loader, client\n\n spec = loader.load_openapi(\"openapi.yaml\")\n\n api = client.OpenAPIClient(\n spec=spec,\n base_url=\"http://localhost:8000\",\n )\n\n # Call operationId: getUser\n response = api.getUser(\n path_params={\"user_id\": 123}\n )\n\n print(response.status_code)\n print(response.json())\n ```", "members": { "spec": { "name": "spec", @@ -268,7 +268,7 @@ "name": "operations", "kind": "function", "path": "openapi_first.client.OpenAPIClient.operations", - "signature": "", + "signature": "", "docstring": null } } @@ -280,21 +280,21 @@ "kind": "module", "path": "openapi_first.errors", "signature": null, - "docstring": "openapi_first.errors\n============================\n\nCustom exceptions for OpenAPI-first FastAPI applications.\n\nThis module defines a small hierarchy of explicit, intention-revealing\nexceptions used to signal contract violations between an OpenAPI\nspecification and its Python implementation.\n\nDesign principles\n-----------------\n- Errors represent *programmer mistakes*, not runtime conditions.\n- All errors are raised during application startup.\n- Messages are actionable and suitable for CI/CD output.\n- Exceptions are explicit rather than reused from generic built-ins.\n\nThese errors should normally cause immediate application failure.", + "docstring": "Exceptions for OpenAPI-first FastAPI applications.\n\n---\n\n## Summary\n\nThis module defines a small hierarchy of explicit, intention-revealing\nexceptions used to signal contract violations between an OpenAPI\nspecification and its Python implementation.\n\nNotes:\n **Design Principles:**\n\n - Errors represent programmer mistakes, not runtime conditions\n - All errors are raised during application startup\n - Messages are actionable and suitable for CI/CD output\n - Exceptions are explicit rather than reused from generic built-ins\n\n These errors should normally cause immediate application failure.", "members": { "OpenAPIFirstError": { "name": "OpenAPIFirstError", "kind": "class", "path": "openapi_first.errors.OpenAPIFirstError", - "signature": "", - "docstring": "Base exception for all OpenAPI-first enforcement errors.\n\nThis exception exists to allow callers, test suites, and CI pipelines\nto catch and distinguish OpenAPI contract violations from unrelated\nruntime errors.\n\nAll exceptions raised by the OpenAPI-first core should inherit from\nthis type." + "signature": "", + "docstring": "Base exception for all OpenAPI-first enforcement errors.\n\nNotes:\n **Responsibilities:**\n\n - This exception exists to allow callers, test suites, and CI pipelines to catch and distinguish OpenAPI contract violations from unrelated runtime errors\n - All exceptions raised by the OpenAPI-first core should inherit from this type" }, "MissingOperationHandler": { "name": "MissingOperationHandler", "kind": "class", "path": "openapi_first.errors.MissingOperationHandler", - "signature": "", - "docstring": "Raised when an OpenAPI operation cannot be resolved to a handler.\n\nThis error occurs when:\n- An OpenAPI operation does not define an operationId, or\n- An operationId is defined but no matching function exists in the\n provided routes module.\n\nThis represents a violation of the OpenAPI-first contract and\nindicates that the specification and implementation are out of sync." + "signature": "", + "docstring": "Raised when an OpenAPI operation cannot be resolved to a handler.\n\nNotes:\n **Scenarios:**\n\n - An OpenAPI operation does not define an operationId\n - An operationId is defined but no matching function exists in the provided routes module\n\n **Guarantees:**\n\n - This represents a violation of the OpenAPI-first contract and indicates that the specification and implementation are out of sync" }, "Optional": { "name": "Optional", @@ -310,7 +310,7 @@ "kind": "module", "path": "openapi_first.loader", "signature": null, - "docstring": "openapi_first.loaders\n=============================\n\nOpenAPI specification loading and validation utilities.\n\nThis module is responsible for loading an OpenAPI 3.x specification\nfrom disk and validating it before it is used by the application.\n\nIt enforces the principle that an invalid or malformed OpenAPI document\nmust never reach the routing or runtime layers.\n\nDesign principles\n-----------------\n- OpenAPI is treated as an authoritative contract.\n- Invalid specifications fail fast at application startup.\n- Supported formats are JSON and YAML.\n- Validation errors are surfaced clearly and early.\n\nThis module intentionally does NOT:\n-----------------------------------\n- Modify the OpenAPI document\n- Infer missing fields\n- Generate models or code\n- Perform request/response validation at runtime", + "docstring": "OpenAPI specification loading and validation utilities.\n\n---\n\n## Summary\n\nThis module is responsible for loading an OpenAPI 3.x specification\nfrom disk and validating it before it is used by the application.\n\nIt enforces the principle that an invalid or malformed OpenAPI document\nmust never reach the routing or runtime layers.\n\nNotes:\n **Design Principles:**\n\n - OpenAPI is treated as an authoritative contract\n - Invalid specifications fail fast at application startup\n - Supported formats are JSON and YAML\n - Validation errors are surfaced clearly and early\n\n **Constraints:**\n\n - This module intentionally does NOT: Modify the OpenAPI document, infer missing fields, generate models or code, or perform request/response validation at runtime.", "members": { "json": { "name": "json", @@ -352,21 +352,21 @@ "kind": "class", "path": "openapi_first.loader.OpenAPIFirstError", "signature": "", - "docstring": "Base exception for all OpenAPI-first enforcement errors.\n\nThis exception exists to allow callers, test suites, and CI pipelines\nto catch and distinguish OpenAPI contract violations from unrelated\nruntime errors.\n\nAll exceptions raised by the OpenAPI-first core should inherit from\nthis type." + "docstring": "Base exception for all OpenAPI-first enforcement errors.\n\nNotes:\n **Responsibilities:**\n\n - This exception exists to allow callers, test suites, and CI pipelines to catch and distinguish OpenAPI contract violations from unrelated runtime errors\n - All exceptions raised by the OpenAPI-first core should inherit from this type" }, "OpenAPISpecLoadError": { "name": "OpenAPISpecLoadError", "kind": "class", "path": "openapi_first.loader.OpenAPISpecLoadError", - "signature": "", - "docstring": "Raised when an OpenAPI specification cannot be loaded or validated.\n\nThis error indicates that the OpenAPI document is unreadable,\nmalformed, or violates the OpenAPI 3.x specification." + "signature": "", + "docstring": "Raised when an OpenAPI specification cannot be loaded or validated.\n\nNotes:\n **Guarantees:**\n\n - This error indicates that the OpenAPI document is unreadable, malformed, or violates the OpenAPI 3.x specification" }, "load_openapi": { "name": "load_openapi", "kind": "function", "path": "openapi_first.loader.load_openapi", - "signature": "", - "docstring": "Load and validate an OpenAPI 3.x specification from disk.\n\nThe specification is parsed based on file extension and validated\nusing a strict OpenAPI schema validator. Any error results in an\nimmediate exception, preventing application startup.\n\nParameters\n----------\npath : str or pathlib.Path\n Filesystem path to an OpenAPI specification file.\n Supported extensions:\n - `.json`\n - `.yaml`\n - `.yml`\n\nReturns\n-------\ndict\n Parsed and validated OpenAPI specification.\n\nRaises\n------\nOpenAPISpecLoadError\n If the file does not exist, cannot be parsed, or fails\n OpenAPI schema validation." + "signature": "", + "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" }, "Dict": { "name": "Dict", @@ -461,7 +461,7 @@ "kind": "class", "path": "openapi_first.templates.crud_app.main.OpenAPIFirstApp", "signature": "", - "docstring": "FastAPI application enforcing OpenAPI-first design.\n\n`OpenAPIFirstApp` subclasses FastAPI and replaces manual route\nregistration with OpenAPI-driven binding. All routes are derived\nfrom the provided OpenAPI specification, and each operationId is\nmapped to a Python function in the supplied routes module.\n\nParameters\n----------\nopenapi_path : str\n Filesystem path to the OpenAPI 3.x specification file.\n This specification is treated as the authoritative API contract.\n\nroutes_module : module\n Python module containing handler functions whose names correspond\n exactly to OpenAPI operationId values.\n\n**fastapi_kwargs\n Additional keyword arguments passed directly to `fastapi.FastAPI`\n (e.g., title, version, middleware, lifespan handlers).\n\nRaises\n------\nOpenAPIFirstError\n If the OpenAPI specification is invalid, or if any declared\n operationId does not have a corresponding handler function.\n\nBehavior 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-------\n```python\nfrom openapi_first import OpenAPIFirstApp\nimport app.routes as routes\n\napp = OpenAPIFirstApp(\n openapi_path=\"app/openapi.json\",\n routes_module=routes,\n title=\"Example Service\",\n)\n```", + "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", @@ -572,14 +572,14 @@ "kind": "function", "path": "openapi_first.templates.crud_app.test_crud_app.load_openapi", "signature": "", - "docstring": "Load and validate an OpenAPI 3.x specification from disk.\n\nThe specification is parsed based on file extension and validated\nusing a strict OpenAPI schema validator. Any error results in an\nimmediate exception, preventing application startup.\n\nParameters\n----------\npath : str or pathlib.Path\n Filesystem path to an OpenAPI specification file.\n Supported extensions:\n - `.json`\n - `.yaml`\n - `.yml`\n\nReturns\n-------\ndict\n Parsed and validated OpenAPI specification.\n\nRaises\n------\nOpenAPISpecLoadError\n If the file does not exist, cannot be parsed, or fails\n OpenAPI schema validation." + "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" }, "OpenAPIClient": { "name": "OpenAPIClient", "kind": "class", "path": "openapi_first.templates.crud_app.test_crud_app.OpenAPIClient", "signature": "", - "docstring": "OpenAPI-first HTTP client (httpx-based).\n\nThis client derives all callable methods directly from an OpenAPI 3.x\nspecification. Each operationId becomes a method on the client\ninstance.\n\nDesign principles\n-----------------\n- One callable per operationId\n- Explicit parameters (path, query, headers, body)\n- No implicit schema inference or mutation\n- Returns raw httpx.Response objects\n- No response validation or deserialization\n\nParameters\n----------\nspec : dict\n Parsed OpenAPI 3.x specification.\nbase_url : str | None\n Base URL of the target service. If omitted, the first entry\n in the OpenAPI `servers` list is used.\nclient : httpx.Client | None\n Optional preconfigured httpx client instance.\n\nRaises\n------\nOpenAPIClientError\n If:\n - No servers are defined and base_url is not provided\n - OpenAPI spec has no paths\n - An operation is missing operationId\n - Duplicate operationIds are detected\n - Required path parameters are missing\n - Required request body is missing\n\n Example\n-------\n```python\nfrom openapi_first import loader, client\n\nspec = loader.load_openapi(\"openapi.yaml\")\n\napi = client.OpenAPIClient(\n spec=spec,\n base_url=\"http://localhost:8000\",\n)\n\n# Call operationId: getUser\nresponse = api.getUser(\n path_params={\"user_id\": 123}\n)\n\nprint(response.status_code)\nprint(response.json())\n\n# Call operationId: createUser\nresponse = api.createUser(\n body={\"name\": \"Bob\"}\n)\n\nprint(response.status_code)\n```", + "docstring": "OpenAPI-first HTTP client (httpx-based).\n\nNotes:\n **Responsibilities:**\n\n - This client derives all callable methods directly from an OpenAPI 3.x specification. Each operationId becomes a method on the client instance.\n\n **Guarantees:**\n\n - One callable per operationId\n - Explicit parameters (path, query, headers, body)\n - No implicit schema inference or mutation\n - Returns raw `httpx.Response` objects\n - No response validation or deserialization\n\nExample:\n ```python\n from openapi_first import loader, client\n\n spec = loader.load_openapi(\"openapi.yaml\")\n\n api = client.OpenAPIClient(\n spec=spec,\n base_url=\"http://localhost:8000\",\n )\n\n # Call operationId: getUser\n response = api.getUser(\n path_params={\"user_id\": 123}\n )\n\n print(response.status_code)\n print(response.json())\n ```", "members": { "spec": { "name": "spec", @@ -683,7 +683,7 @@ "kind": "class", "path": "openapi_first.templates.health_app.main.OpenAPIFirstApp", "signature": "", - "docstring": "FastAPI application enforcing OpenAPI-first design.\n\n`OpenAPIFirstApp` subclasses FastAPI and replaces manual route\nregistration with OpenAPI-driven binding. All routes are derived\nfrom the provided OpenAPI specification, and each operationId is\nmapped to a Python function in the supplied routes module.\n\nParameters\n----------\nopenapi_path : str\n Filesystem path to the OpenAPI 3.x specification file.\n This specification is treated as the authoritative API contract.\n\nroutes_module : module\n Python module containing handler functions whose names correspond\n exactly to OpenAPI operationId values.\n\n**fastapi_kwargs\n Additional keyword arguments passed directly to `fastapi.FastAPI`\n (e.g., title, version, middleware, lifespan handlers).\n\nRaises\n------\nOpenAPIFirstError\n If the OpenAPI specification is invalid, or if any declared\n operationId does not have a corresponding handler function.\n\nBehavior 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-------\n```python\nfrom openapi_first import OpenAPIFirstApp\nimport app.routes as routes\n\napp = OpenAPIFirstApp(\n openapi_path=\"app/openapi.json\",\n routes_module=routes,\n title=\"Example Service\",\n)\n```", + "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", @@ -812,7 +812,7 @@ "kind": "class", "path": "openapi_first.templates.model_app.main.OpenAPIFirstApp", "signature": "", - "docstring": "FastAPI application enforcing OpenAPI-first design.\n\n`OpenAPIFirstApp` subclasses FastAPI and replaces manual route\nregistration with OpenAPI-driven binding. All routes are derived\nfrom the provided OpenAPI specification, and each operationId is\nmapped to a Python function in the supplied routes module.\n\nParameters\n----------\nopenapi_path : str\n Filesystem path to the OpenAPI 3.x specification file.\n This specification is treated as the authoritative API contract.\n\nroutes_module : module\n Python module containing handler functions whose names correspond\n exactly to OpenAPI operationId values.\n\n**fastapi_kwargs\n Additional keyword arguments passed directly to `fastapi.FastAPI`\n (e.g., title, version, middleware, lifespan handlers).\n\nRaises\n------\nOpenAPIFirstError\n If the OpenAPI specification is invalid, or if any declared\n operationId does not have a corresponding handler function.\n\nBehavior 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-------\n```python\nfrom openapi_first import OpenAPIFirstApp\nimport app.routes as routes\n\napp = OpenAPIFirstApp(\n openapi_path=\"app/openapi.json\",\n routes_module=routes,\n title=\"Example Service\",\n)\n```", + "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", @@ -992,14 +992,14 @@ "kind": "function", "path": "openapi_first.templates.model_app.test_model_app.load_openapi", "signature": "", - "docstring": "Load and validate an OpenAPI 3.x specification from disk.\n\nThe specification is parsed based on file extension and validated\nusing a strict OpenAPI schema validator. Any error results in an\nimmediate exception, preventing application startup.\n\nParameters\n----------\npath : str or pathlib.Path\n Filesystem path to an OpenAPI specification file.\n Supported extensions:\n - `.json`\n - `.yaml`\n - `.yml`\n\nReturns\n-------\ndict\n Parsed and validated OpenAPI specification.\n\nRaises\n------\nOpenAPISpecLoadError\n If the file does not exist, cannot be parsed, or fails\n OpenAPI schema validation." + "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" }, "OpenAPIClient": { "name": "OpenAPIClient", "kind": "class", "path": "openapi_first.templates.model_app.test_model_app.OpenAPIClient", "signature": "", - "docstring": "OpenAPI-first HTTP client (httpx-based).\n\nThis client derives all callable methods directly from an OpenAPI 3.x\nspecification. Each operationId becomes a method on the client\ninstance.\n\nDesign principles\n-----------------\n- One callable per operationId\n- Explicit parameters (path, query, headers, body)\n- No implicit schema inference or mutation\n- Returns raw httpx.Response objects\n- No response validation or deserialization\n\nParameters\n----------\nspec : dict\n Parsed OpenAPI 3.x specification.\nbase_url : str | None\n Base URL of the target service. If omitted, the first entry\n in the OpenAPI `servers` list is used.\nclient : httpx.Client | None\n Optional preconfigured httpx client instance.\n\nRaises\n------\nOpenAPIClientError\n If:\n - No servers are defined and base_url is not provided\n - OpenAPI spec has no paths\n - An operation is missing operationId\n - Duplicate operationIds are detected\n - Required path parameters are missing\n - Required request body is missing\n\n Example\n-------\n```python\nfrom openapi_first import loader, client\n\nspec = loader.load_openapi(\"openapi.yaml\")\n\napi = client.OpenAPIClient(\n spec=spec,\n base_url=\"http://localhost:8000\",\n)\n\n# Call operationId: getUser\nresponse = api.getUser(\n path_params={\"user_id\": 123}\n)\n\nprint(response.status_code)\nprint(response.json())\n\n# Call operationId: createUser\nresponse = api.createUser(\n body={\"name\": \"Bob\"}\n)\n\nprint(response.status_code)\n```", + "docstring": "OpenAPI-first HTTP client (httpx-based).\n\nNotes:\n **Responsibilities:**\n\n - This client derives all callable methods directly from an OpenAPI 3.x specification. Each operationId becomes a method on the client instance.\n\n **Guarantees:**\n\n - One callable per operationId\n - Explicit parameters (path, query, headers, body)\n - No implicit schema inference or mutation\n - Returns raw `httpx.Response` objects\n - No response validation or deserialization\n\nExample:\n ```python\n from openapi_first import loader, client\n\n spec = loader.load_openapi(\"openapi.yaml\")\n\n api = client.OpenAPIClient(\n spec=spec,\n base_url=\"http://localhost:8000\",\n )\n\n # Call operationId: getUser\n response = api.getUser(\n path_params={\"user_id\": 123}\n )\n\n print(response.status_code)\n print(response.json())\n ```", "members": { "spec": { "name": "spec", diff --git a/mcp_docs/modules/openapi_first.loader.json b/mcp_docs/modules/openapi_first.loader.json index 1fbddf6..dcf398a 100644 --- a/mcp_docs/modules/openapi_first.loader.json +++ b/mcp_docs/modules/openapi_first.loader.json @@ -2,7 +2,7 @@ "module": "openapi_first.loader", "content": { "path": "openapi_first.loader", - "docstring": "openapi_first.loaders\n=============================\n\nOpenAPI specification loading and validation utilities.\n\nThis module is responsible for loading an OpenAPI 3.x specification\nfrom disk and validating it before it is used by the application.\n\nIt enforces the principle that an invalid or malformed OpenAPI document\nmust never reach the routing or runtime layers.\n\nDesign principles\n-----------------\n- OpenAPI is treated as an authoritative contract.\n- Invalid specifications fail fast at application startup.\n- Supported formats are JSON and YAML.\n- Validation errors are surfaced clearly and early.\n\nThis module intentionally does NOT:\n-----------------------------------\n- Modify the OpenAPI document\n- Infer missing fields\n- Generate models or code\n- Perform request/response validation at runtime", + "docstring": "OpenAPI specification loading and validation utilities.\n\n---\n\n## Summary\n\nThis module is responsible for loading an OpenAPI 3.x specification\nfrom disk and validating it before it is used by the application.\n\nIt enforces the principle that an invalid or malformed OpenAPI document\nmust never reach the routing or runtime layers.\n\nNotes:\n **Design Principles:**\n\n - OpenAPI is treated as an authoritative contract\n - Invalid specifications fail fast at application startup\n - Supported formats are JSON and YAML\n - Validation errors are surfaced clearly and early\n\n **Constraints:**\n\n - This module intentionally does NOT: Modify the OpenAPI document, infer missing fields, generate models or code, or perform request/response validation at runtime.", "objects": { "json": { "name": "json", @@ -44,21 +44,21 @@ "kind": "class", "path": "openapi_first.loader.OpenAPIFirstError", "signature": "", - "docstring": "Base exception for all OpenAPI-first enforcement errors.\n\nThis exception exists to allow callers, test suites, and CI pipelines\nto catch and distinguish OpenAPI contract violations from unrelated\nruntime errors.\n\nAll exceptions raised by the OpenAPI-first core should inherit from\nthis type." + "docstring": "Base exception for all OpenAPI-first enforcement errors.\n\nNotes:\n **Responsibilities:**\n\n - This exception exists to allow callers, test suites, and CI pipelines to catch and distinguish OpenAPI contract violations from unrelated runtime errors\n - All exceptions raised by the OpenAPI-first core should inherit from this type" }, "OpenAPISpecLoadError": { "name": "OpenAPISpecLoadError", "kind": "class", "path": "openapi_first.loader.OpenAPISpecLoadError", - "signature": "", - "docstring": "Raised when an OpenAPI specification cannot be loaded or validated.\n\nThis error indicates that the OpenAPI document is unreadable,\nmalformed, or violates the OpenAPI 3.x specification." + "signature": "", + "docstring": "Raised when an OpenAPI specification cannot be loaded or validated.\n\nNotes:\n **Guarantees:**\n\n - This error indicates that the OpenAPI document is unreadable, malformed, or violates the OpenAPI 3.x specification" }, "load_openapi": { "name": "load_openapi", "kind": "function", "path": "openapi_first.loader.load_openapi", - "signature": "", - "docstring": "Load and validate an OpenAPI 3.x specification from disk.\n\nThe specification is parsed based on file extension and validated\nusing a strict OpenAPI schema validator. Any error results in an\nimmediate exception, preventing application startup.\n\nParameters\n----------\npath : str or pathlib.Path\n Filesystem path to an OpenAPI specification file.\n Supported extensions:\n - `.json`\n - `.yaml`\n - `.yml`\n\nReturns\n-------\ndict\n Parsed and validated OpenAPI specification.\n\nRaises\n------\nOpenAPISpecLoadError\n If the file does not exist, cannot be parsed, or fails\n OpenAPI schema validation." + "signature": "", + "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" }, "Dict": { "name": "Dict", diff --git a/mcp_docs/modules/openapi_first.templates.crud_app.json b/mcp_docs/modules/openapi_first.templates.crud_app.json index de58301..6ce939c 100644 --- a/mcp_docs/modules/openapi_first.templates.crud_app.json +++ b/mcp_docs/modules/openapi_first.templates.crud_app.json @@ -67,7 +67,7 @@ "kind": "class", "path": "openapi_first.templates.crud_app.main.OpenAPIFirstApp", "signature": "", - "docstring": "FastAPI application enforcing OpenAPI-first design.\n\n`OpenAPIFirstApp` subclasses FastAPI and replaces manual route\nregistration with OpenAPI-driven binding. All routes are derived\nfrom the provided OpenAPI specification, and each operationId is\nmapped to a Python function in the supplied routes module.\n\nParameters\n----------\nopenapi_path : str\n Filesystem path to the OpenAPI 3.x specification file.\n This specification is treated as the authoritative API contract.\n\nroutes_module : module\n Python module containing handler functions whose names correspond\n exactly to OpenAPI operationId values.\n\n**fastapi_kwargs\n Additional keyword arguments passed directly to `fastapi.FastAPI`\n (e.g., title, version, middleware, lifespan handlers).\n\nRaises\n------\nOpenAPIFirstError\n If the OpenAPI specification is invalid, or if any declared\n operationId does not have a corresponding handler function.\n\nBehavior 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-------\n```python\nfrom openapi_first import OpenAPIFirstApp\nimport app.routes as routes\n\napp = OpenAPIFirstApp(\n openapi_path=\"app/openapi.json\",\n routes_module=routes,\n title=\"Example Service\",\n)\n```", + "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", @@ -178,14 +178,14 @@ "kind": "function", "path": "openapi_first.templates.crud_app.test_crud_app.load_openapi", "signature": "", - "docstring": "Load and validate an OpenAPI 3.x specification from disk.\n\nThe specification is parsed based on file extension and validated\nusing a strict OpenAPI schema validator. Any error results in an\nimmediate exception, preventing application startup.\n\nParameters\n----------\npath : str or pathlib.Path\n Filesystem path to an OpenAPI specification file.\n Supported extensions:\n - `.json`\n - `.yaml`\n - `.yml`\n\nReturns\n-------\ndict\n Parsed and validated OpenAPI specification.\n\nRaises\n------\nOpenAPISpecLoadError\n If the file does not exist, cannot be parsed, or fails\n OpenAPI schema validation." + "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" }, "OpenAPIClient": { "name": "OpenAPIClient", "kind": "class", "path": "openapi_first.templates.crud_app.test_crud_app.OpenAPIClient", "signature": "", - "docstring": "OpenAPI-first HTTP client (httpx-based).\n\nThis client derives all callable methods directly from an OpenAPI 3.x\nspecification. Each operationId becomes a method on the client\ninstance.\n\nDesign principles\n-----------------\n- One callable per operationId\n- Explicit parameters (path, query, headers, body)\n- No implicit schema inference or mutation\n- Returns raw httpx.Response objects\n- No response validation or deserialization\n\nParameters\n----------\nspec : dict\n Parsed OpenAPI 3.x specification.\nbase_url : str | None\n Base URL of the target service. If omitted, the first entry\n in the OpenAPI `servers` list is used.\nclient : httpx.Client | None\n Optional preconfigured httpx client instance.\n\nRaises\n------\nOpenAPIClientError\n If:\n - No servers are defined and base_url is not provided\n - OpenAPI spec has no paths\n - An operation is missing operationId\n - Duplicate operationIds are detected\n - Required path parameters are missing\n - Required request body is missing\n\n Example\n-------\n```python\nfrom openapi_first import loader, client\n\nspec = loader.load_openapi(\"openapi.yaml\")\n\napi = client.OpenAPIClient(\n spec=spec,\n base_url=\"http://localhost:8000\",\n)\n\n# Call operationId: getUser\nresponse = api.getUser(\n path_params={\"user_id\": 123}\n)\n\nprint(response.status_code)\nprint(response.json())\n\n# Call operationId: createUser\nresponse = api.createUser(\n body={\"name\": \"Bob\"}\n)\n\nprint(response.status_code)\n```", + "docstring": "OpenAPI-first HTTP client (httpx-based).\n\nNotes:\n **Responsibilities:**\n\n - This client derives all callable methods directly from an OpenAPI 3.x specification. Each operationId becomes a method on the client instance.\n\n **Guarantees:**\n\n - One callable per operationId\n - Explicit parameters (path, query, headers, body)\n - No implicit schema inference or mutation\n - Returns raw `httpx.Response` objects\n - No response validation or deserialization\n\nExample:\n ```python\n from openapi_first import loader, client\n\n spec = loader.load_openapi(\"openapi.yaml\")\n\n api = client.OpenAPIClient(\n spec=spec,\n base_url=\"http://localhost:8000\",\n )\n\n # Call operationId: getUser\n response = api.getUser(\n path_params={\"user_id\": 123}\n )\n\n print(response.status_code)\n print(response.json())\n ```", "members": { "spec": { "name": "spec", diff --git a/mcp_docs/modules/openapi_first.templates.crud_app.main.json b/mcp_docs/modules/openapi_first.templates.crud_app.main.json index 2cc9fa3..a3c6ef1 100644 --- a/mcp_docs/modules/openapi_first.templates.crud_app.main.json +++ b/mcp_docs/modules/openapi_first.templates.crud_app.main.json @@ -9,7 +9,7 @@ "kind": "class", "path": "openapi_first.templates.crud_app.main.OpenAPIFirstApp", "signature": "", - "docstring": "FastAPI application enforcing OpenAPI-first design.\n\n`OpenAPIFirstApp` subclasses FastAPI and replaces manual route\nregistration with OpenAPI-driven binding. All routes are derived\nfrom the provided OpenAPI specification, and each operationId is\nmapped to a Python function in the supplied routes module.\n\nParameters\n----------\nopenapi_path : str\n Filesystem path to the OpenAPI 3.x specification file.\n This specification is treated as the authoritative API contract.\n\nroutes_module : module\n Python module containing handler functions whose names correspond\n exactly to OpenAPI operationId values.\n\n**fastapi_kwargs\n Additional keyword arguments passed directly to `fastapi.FastAPI`\n (e.g., title, version, middleware, lifespan handlers).\n\nRaises\n------\nOpenAPIFirstError\n If the OpenAPI specification is invalid, or if any declared\n operationId does not have a corresponding handler function.\n\nBehavior 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-------\n```python\nfrom openapi_first import OpenAPIFirstApp\nimport app.routes as routes\n\napp = OpenAPIFirstApp(\n openapi_path=\"app/openapi.json\",\n routes_module=routes,\n title=\"Example Service\",\n)\n```", + "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", diff --git a/mcp_docs/modules/openapi_first.templates.crud_app.test_crud_app.json b/mcp_docs/modules/openapi_first.templates.crud_app.test_crud_app.json index 7c14f24..6b95c8f 100644 --- a/mcp_docs/modules/openapi_first.templates.crud_app.test_crud_app.json +++ b/mcp_docs/modules/openapi_first.templates.crud_app.test_crud_app.json @@ -23,14 +23,14 @@ "kind": "function", "path": "openapi_first.templates.crud_app.test_crud_app.load_openapi", "signature": "", - "docstring": "Load and validate an OpenAPI 3.x specification from disk.\n\nThe specification is parsed based on file extension and validated\nusing a strict OpenAPI schema validator. Any error results in an\nimmediate exception, preventing application startup.\n\nParameters\n----------\npath : str or pathlib.Path\n Filesystem path to an OpenAPI specification file.\n Supported extensions:\n - `.json`\n - `.yaml`\n - `.yml`\n\nReturns\n-------\ndict\n Parsed and validated OpenAPI specification.\n\nRaises\n------\nOpenAPISpecLoadError\n If the file does not exist, cannot be parsed, or fails\n OpenAPI schema validation." + "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" }, "OpenAPIClient": { "name": "OpenAPIClient", "kind": "class", "path": "openapi_first.templates.crud_app.test_crud_app.OpenAPIClient", "signature": "", - "docstring": "OpenAPI-first HTTP client (httpx-based).\n\nThis client derives all callable methods directly from an OpenAPI 3.x\nspecification. Each operationId becomes a method on the client\ninstance.\n\nDesign principles\n-----------------\n- One callable per operationId\n- Explicit parameters (path, query, headers, body)\n- No implicit schema inference or mutation\n- Returns raw httpx.Response objects\n- No response validation or deserialization\n\nParameters\n----------\nspec : dict\n Parsed OpenAPI 3.x specification.\nbase_url : str | None\n Base URL of the target service. If omitted, the first entry\n in the OpenAPI `servers` list is used.\nclient : httpx.Client | None\n Optional preconfigured httpx client instance.\n\nRaises\n------\nOpenAPIClientError\n If:\n - No servers are defined and base_url is not provided\n - OpenAPI spec has no paths\n - An operation is missing operationId\n - Duplicate operationIds are detected\n - Required path parameters are missing\n - Required request body is missing\n\n Example\n-------\n```python\nfrom openapi_first import loader, client\n\nspec = loader.load_openapi(\"openapi.yaml\")\n\napi = client.OpenAPIClient(\n spec=spec,\n base_url=\"http://localhost:8000\",\n)\n\n# Call operationId: getUser\nresponse = api.getUser(\n path_params={\"user_id\": 123}\n)\n\nprint(response.status_code)\nprint(response.json())\n\n# Call operationId: createUser\nresponse = api.createUser(\n body={\"name\": \"Bob\"}\n)\n\nprint(response.status_code)\n```", + "docstring": "OpenAPI-first HTTP client (httpx-based).\n\nNotes:\n **Responsibilities:**\n\n - This client derives all callable methods directly from an OpenAPI 3.x specification. Each operationId becomes a method on the client instance.\n\n **Guarantees:**\n\n - One callable per operationId\n - Explicit parameters (path, query, headers, body)\n - No implicit schema inference or mutation\n - Returns raw `httpx.Response` objects\n - No response validation or deserialization\n\nExample:\n ```python\n from openapi_first import loader, client\n\n spec = loader.load_openapi(\"openapi.yaml\")\n\n api = client.OpenAPIClient(\n spec=spec,\n base_url=\"http://localhost:8000\",\n )\n\n # Call operationId: getUser\n response = api.getUser(\n path_params={\"user_id\": 123}\n )\n\n print(response.status_code)\n print(response.json())\n ```", "members": { "spec": { "name": "spec", diff --git a/mcp_docs/modules/openapi_first.templates.health_app.json b/mcp_docs/modules/openapi_first.templates.health_app.json index 3648d6f..7f55637 100644 --- a/mcp_docs/modules/openapi_first.templates.health_app.json +++ b/mcp_docs/modules/openapi_first.templates.health_app.json @@ -16,7 +16,7 @@ "kind": "class", "path": "openapi_first.templates.health_app.main.OpenAPIFirstApp", "signature": "", - "docstring": "FastAPI application enforcing OpenAPI-first design.\n\n`OpenAPIFirstApp` subclasses FastAPI and replaces manual route\nregistration with OpenAPI-driven binding. All routes are derived\nfrom the provided OpenAPI specification, and each operationId is\nmapped to a Python function in the supplied routes module.\n\nParameters\n----------\nopenapi_path : str\n Filesystem path to the OpenAPI 3.x specification file.\n This specification is treated as the authoritative API contract.\n\nroutes_module : module\n Python module containing handler functions whose names correspond\n exactly to OpenAPI operationId values.\n\n**fastapi_kwargs\n Additional keyword arguments passed directly to `fastapi.FastAPI`\n (e.g., title, version, middleware, lifespan handlers).\n\nRaises\n------\nOpenAPIFirstError\n If the OpenAPI specification is invalid, or if any declared\n operationId does not have a corresponding handler function.\n\nBehavior 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-------\n```python\nfrom openapi_first import OpenAPIFirstApp\nimport app.routes as routes\n\napp = OpenAPIFirstApp(\n openapi_path=\"app/openapi.json\",\n routes_module=routes,\n title=\"Example Service\",\n)\n```", + "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", diff --git a/mcp_docs/modules/openapi_first.templates.health_app.main.json b/mcp_docs/modules/openapi_first.templates.health_app.main.json index 49785ca..f81ea77 100644 --- a/mcp_docs/modules/openapi_first.templates.health_app.main.json +++ b/mcp_docs/modules/openapi_first.templates.health_app.main.json @@ -9,7 +9,7 @@ "kind": "class", "path": "openapi_first.templates.health_app.main.OpenAPIFirstApp", "signature": "", - "docstring": "FastAPI application enforcing OpenAPI-first design.\n\n`OpenAPIFirstApp` subclasses FastAPI and replaces manual route\nregistration with OpenAPI-driven binding. All routes are derived\nfrom the provided OpenAPI specification, and each operationId is\nmapped to a Python function in the supplied routes module.\n\nParameters\n----------\nopenapi_path : str\n Filesystem path to the OpenAPI 3.x specification file.\n This specification is treated as the authoritative API contract.\n\nroutes_module : module\n Python module containing handler functions whose names correspond\n exactly to OpenAPI operationId values.\n\n**fastapi_kwargs\n Additional keyword arguments passed directly to `fastapi.FastAPI`\n (e.g., title, version, middleware, lifespan handlers).\n\nRaises\n------\nOpenAPIFirstError\n If the OpenAPI specification is invalid, or if any declared\n operationId does not have a corresponding handler function.\n\nBehavior 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-------\n```python\nfrom openapi_first import OpenAPIFirstApp\nimport app.routes as routes\n\napp = OpenAPIFirstApp(\n openapi_path=\"app/openapi.json\",\n routes_module=routes,\n title=\"Example Service\",\n)\n```", + "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", diff --git a/mcp_docs/modules/openapi_first.templates.json b/mcp_docs/modules/openapi_first.templates.json index 6511ef0..ca5650e 100644 --- a/mcp_docs/modules/openapi_first.templates.json +++ b/mcp_docs/modules/openapi_first.templates.json @@ -74,7 +74,7 @@ "kind": "class", "path": "openapi_first.templates.crud_app.main.OpenAPIFirstApp", "signature": "", - "docstring": "FastAPI application enforcing OpenAPI-first design.\n\n`OpenAPIFirstApp` subclasses FastAPI and replaces manual route\nregistration with OpenAPI-driven binding. All routes are derived\nfrom the provided OpenAPI specification, and each operationId is\nmapped to a Python function in the supplied routes module.\n\nParameters\n----------\nopenapi_path : str\n Filesystem path to the OpenAPI 3.x specification file.\n This specification is treated as the authoritative API contract.\n\nroutes_module : module\n Python module containing handler functions whose names correspond\n exactly to OpenAPI operationId values.\n\n**fastapi_kwargs\n Additional keyword arguments passed directly to `fastapi.FastAPI`\n (e.g., title, version, middleware, lifespan handlers).\n\nRaises\n------\nOpenAPIFirstError\n If the OpenAPI specification is invalid, or if any declared\n operationId does not have a corresponding handler function.\n\nBehavior 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-------\n```python\nfrom openapi_first import OpenAPIFirstApp\nimport app.routes as routes\n\napp = OpenAPIFirstApp(\n openapi_path=\"app/openapi.json\",\n routes_module=routes,\n title=\"Example Service\",\n)\n```", + "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", @@ -185,14 +185,14 @@ "kind": "function", "path": "openapi_first.templates.crud_app.test_crud_app.load_openapi", "signature": "", - "docstring": "Load and validate an OpenAPI 3.x specification from disk.\n\nThe specification is parsed based on file extension and validated\nusing a strict OpenAPI schema validator. Any error results in an\nimmediate exception, preventing application startup.\n\nParameters\n----------\npath : str or pathlib.Path\n Filesystem path to an OpenAPI specification file.\n Supported extensions:\n - `.json`\n - `.yaml`\n - `.yml`\n\nReturns\n-------\ndict\n Parsed and validated OpenAPI specification.\n\nRaises\n------\nOpenAPISpecLoadError\n If the file does not exist, cannot be parsed, or fails\n OpenAPI schema validation." + "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" }, "OpenAPIClient": { "name": "OpenAPIClient", "kind": "class", "path": "openapi_first.templates.crud_app.test_crud_app.OpenAPIClient", "signature": "", - "docstring": "OpenAPI-first HTTP client (httpx-based).\n\nThis client derives all callable methods directly from an OpenAPI 3.x\nspecification. Each operationId becomes a method on the client\ninstance.\n\nDesign principles\n-----------------\n- One callable per operationId\n- Explicit parameters (path, query, headers, body)\n- No implicit schema inference or mutation\n- Returns raw httpx.Response objects\n- No response validation or deserialization\n\nParameters\n----------\nspec : dict\n Parsed OpenAPI 3.x specification.\nbase_url : str | None\n Base URL of the target service. If omitted, the first entry\n in the OpenAPI `servers` list is used.\nclient : httpx.Client | None\n Optional preconfigured httpx client instance.\n\nRaises\n------\nOpenAPIClientError\n If:\n - No servers are defined and base_url is not provided\n - OpenAPI spec has no paths\n - An operation is missing operationId\n - Duplicate operationIds are detected\n - Required path parameters are missing\n - Required request body is missing\n\n Example\n-------\n```python\nfrom openapi_first import loader, client\n\nspec = loader.load_openapi(\"openapi.yaml\")\n\napi = client.OpenAPIClient(\n spec=spec,\n base_url=\"http://localhost:8000\",\n)\n\n# Call operationId: getUser\nresponse = api.getUser(\n path_params={\"user_id\": 123}\n)\n\nprint(response.status_code)\nprint(response.json())\n\n# Call operationId: createUser\nresponse = api.createUser(\n body={\"name\": \"Bob\"}\n)\n\nprint(response.status_code)\n```", + "docstring": "OpenAPI-first HTTP client (httpx-based).\n\nNotes:\n **Responsibilities:**\n\n - This client derives all callable methods directly from an OpenAPI 3.x specification. Each operationId becomes a method on the client instance.\n\n **Guarantees:**\n\n - One callable per operationId\n - Explicit parameters (path, query, headers, body)\n - No implicit schema inference or mutation\n - Returns raw `httpx.Response` objects\n - No response validation or deserialization\n\nExample:\n ```python\n from openapi_first import loader, client\n\n spec = loader.load_openapi(\"openapi.yaml\")\n\n api = client.OpenAPIClient(\n spec=spec,\n base_url=\"http://localhost:8000\",\n )\n\n # Call operationId: getUser\n response = api.getUser(\n path_params={\"user_id\": 123}\n )\n\n print(response.status_code)\n print(response.json())\n ```", "members": { "spec": { "name": "spec", @@ -296,7 +296,7 @@ "kind": "class", "path": "openapi_first.templates.health_app.main.OpenAPIFirstApp", "signature": "", - "docstring": "FastAPI application enforcing OpenAPI-first design.\n\n`OpenAPIFirstApp` subclasses FastAPI and replaces manual route\nregistration with OpenAPI-driven binding. All routes are derived\nfrom the provided OpenAPI specification, and each operationId is\nmapped to a Python function in the supplied routes module.\n\nParameters\n----------\nopenapi_path : str\n Filesystem path to the OpenAPI 3.x specification file.\n This specification is treated as the authoritative API contract.\n\nroutes_module : module\n Python module containing handler functions whose names correspond\n exactly to OpenAPI operationId values.\n\n**fastapi_kwargs\n Additional keyword arguments passed directly to `fastapi.FastAPI`\n (e.g., title, version, middleware, lifespan handlers).\n\nRaises\n------\nOpenAPIFirstError\n If the OpenAPI specification is invalid, or if any declared\n operationId does not have a corresponding handler function.\n\nBehavior 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-------\n```python\nfrom openapi_first import OpenAPIFirstApp\nimport app.routes as routes\n\napp = OpenAPIFirstApp(\n openapi_path=\"app/openapi.json\",\n routes_module=routes,\n title=\"Example Service\",\n)\n```", + "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", @@ -425,7 +425,7 @@ "kind": "class", "path": "openapi_first.templates.model_app.main.OpenAPIFirstApp", "signature": "", - "docstring": "FastAPI application enforcing OpenAPI-first design.\n\n`OpenAPIFirstApp` subclasses FastAPI and replaces manual route\nregistration with OpenAPI-driven binding. All routes are derived\nfrom the provided OpenAPI specification, and each operationId is\nmapped to a Python function in the supplied routes module.\n\nParameters\n----------\nopenapi_path : str\n Filesystem path to the OpenAPI 3.x specification file.\n This specification is treated as the authoritative API contract.\n\nroutes_module : module\n Python module containing handler functions whose names correspond\n exactly to OpenAPI operationId values.\n\n**fastapi_kwargs\n Additional keyword arguments passed directly to `fastapi.FastAPI`\n (e.g., title, version, middleware, lifespan handlers).\n\nRaises\n------\nOpenAPIFirstError\n If the OpenAPI specification is invalid, or if any declared\n operationId does not have a corresponding handler function.\n\nBehavior 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-------\n```python\nfrom openapi_first import OpenAPIFirstApp\nimport app.routes as routes\n\napp = OpenAPIFirstApp(\n openapi_path=\"app/openapi.json\",\n routes_module=routes,\n title=\"Example Service\",\n)\n```", + "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", @@ -605,14 +605,14 @@ "kind": "function", "path": "openapi_first.templates.model_app.test_model_app.load_openapi", "signature": "", - "docstring": "Load and validate an OpenAPI 3.x specification from disk.\n\nThe specification is parsed based on file extension and validated\nusing a strict OpenAPI schema validator. Any error results in an\nimmediate exception, preventing application startup.\n\nParameters\n----------\npath : str or pathlib.Path\n Filesystem path to an OpenAPI specification file.\n Supported extensions:\n - `.json`\n - `.yaml`\n - `.yml`\n\nReturns\n-------\ndict\n Parsed and validated OpenAPI specification.\n\nRaises\n------\nOpenAPISpecLoadError\n If the file does not exist, cannot be parsed, or fails\n OpenAPI schema validation." + "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" }, "OpenAPIClient": { "name": "OpenAPIClient", "kind": "class", "path": "openapi_first.templates.model_app.test_model_app.OpenAPIClient", "signature": "", - "docstring": "OpenAPI-first HTTP client (httpx-based).\n\nThis client derives all callable methods directly from an OpenAPI 3.x\nspecification. Each operationId becomes a method on the client\ninstance.\n\nDesign principles\n-----------------\n- One callable per operationId\n- Explicit parameters (path, query, headers, body)\n- No implicit schema inference or mutation\n- Returns raw httpx.Response objects\n- No response validation or deserialization\n\nParameters\n----------\nspec : dict\n Parsed OpenAPI 3.x specification.\nbase_url : str | None\n Base URL of the target service. If omitted, the first entry\n in the OpenAPI `servers` list is used.\nclient : httpx.Client | None\n Optional preconfigured httpx client instance.\n\nRaises\n------\nOpenAPIClientError\n If:\n - No servers are defined and base_url is not provided\n - OpenAPI spec has no paths\n - An operation is missing operationId\n - Duplicate operationIds are detected\n - Required path parameters are missing\n - Required request body is missing\n\n Example\n-------\n```python\nfrom openapi_first import loader, client\n\nspec = loader.load_openapi(\"openapi.yaml\")\n\napi = client.OpenAPIClient(\n spec=spec,\n base_url=\"http://localhost:8000\",\n)\n\n# Call operationId: getUser\nresponse = api.getUser(\n path_params={\"user_id\": 123}\n)\n\nprint(response.status_code)\nprint(response.json())\n\n# Call operationId: createUser\nresponse = api.createUser(\n body={\"name\": \"Bob\"}\n)\n\nprint(response.status_code)\n```", + "docstring": "OpenAPI-first HTTP client (httpx-based).\n\nNotes:\n **Responsibilities:**\n\n - This client derives all callable methods directly from an OpenAPI 3.x specification. Each operationId becomes a method on the client instance.\n\n **Guarantees:**\n\n - One callable per operationId\n - Explicit parameters (path, query, headers, body)\n - No implicit schema inference or mutation\n - Returns raw `httpx.Response` objects\n - No response validation or deserialization\n\nExample:\n ```python\n from openapi_first import loader, client\n\n spec = loader.load_openapi(\"openapi.yaml\")\n\n api = client.OpenAPIClient(\n spec=spec,\n base_url=\"http://localhost:8000\",\n )\n\n # Call operationId: getUser\n response = api.getUser(\n path_params={\"user_id\": 123}\n )\n\n print(response.status_code)\n print(response.json())\n ```", "members": { "spec": { "name": "spec", diff --git a/mcp_docs/modules/openapi_first.templates.model_app.json b/mcp_docs/modules/openapi_first.templates.model_app.json index b358d03..ef98dbe 100644 --- a/mcp_docs/modules/openapi_first.templates.model_app.json +++ b/mcp_docs/modules/openapi_first.templates.model_app.json @@ -81,7 +81,7 @@ "kind": "class", "path": "openapi_first.templates.model_app.main.OpenAPIFirstApp", "signature": "", - "docstring": "FastAPI application enforcing OpenAPI-first design.\n\n`OpenAPIFirstApp` subclasses FastAPI and replaces manual route\nregistration with OpenAPI-driven binding. All routes are derived\nfrom the provided OpenAPI specification, and each operationId is\nmapped to a Python function in the supplied routes module.\n\nParameters\n----------\nopenapi_path : str\n Filesystem path to the OpenAPI 3.x specification file.\n This specification is treated as the authoritative API contract.\n\nroutes_module : module\n Python module containing handler functions whose names correspond\n exactly to OpenAPI operationId values.\n\n**fastapi_kwargs\n Additional keyword arguments passed directly to `fastapi.FastAPI`\n (e.g., title, version, middleware, lifespan handlers).\n\nRaises\n------\nOpenAPIFirstError\n If the OpenAPI specification is invalid, or if any declared\n operationId does not have a corresponding handler function.\n\nBehavior 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-------\n```python\nfrom openapi_first import OpenAPIFirstApp\nimport app.routes as routes\n\napp = OpenAPIFirstApp(\n openapi_path=\"app/openapi.json\",\n routes_module=routes,\n title=\"Example Service\",\n)\n```", + "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", @@ -261,14 +261,14 @@ "kind": "function", "path": "openapi_first.templates.model_app.test_model_app.load_openapi", "signature": "", - "docstring": "Load and validate an OpenAPI 3.x specification from disk.\n\nThe specification is parsed based on file extension and validated\nusing a strict OpenAPI schema validator. Any error results in an\nimmediate exception, preventing application startup.\n\nParameters\n----------\npath : str or pathlib.Path\n Filesystem path to an OpenAPI specification file.\n Supported extensions:\n - `.json`\n - `.yaml`\n - `.yml`\n\nReturns\n-------\ndict\n Parsed and validated OpenAPI specification.\n\nRaises\n------\nOpenAPISpecLoadError\n If the file does not exist, cannot be parsed, or fails\n OpenAPI schema validation." + "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" }, "OpenAPIClient": { "name": "OpenAPIClient", "kind": "class", "path": "openapi_first.templates.model_app.test_model_app.OpenAPIClient", "signature": "", - "docstring": "OpenAPI-first HTTP client (httpx-based).\n\nThis client derives all callable methods directly from an OpenAPI 3.x\nspecification. Each operationId becomes a method on the client\ninstance.\n\nDesign principles\n-----------------\n- One callable per operationId\n- Explicit parameters (path, query, headers, body)\n- No implicit schema inference or mutation\n- Returns raw httpx.Response objects\n- No response validation or deserialization\n\nParameters\n----------\nspec : dict\n Parsed OpenAPI 3.x specification.\nbase_url : str | None\n Base URL of the target service. If omitted, the first entry\n in the OpenAPI `servers` list is used.\nclient : httpx.Client | None\n Optional preconfigured httpx client instance.\n\nRaises\n------\nOpenAPIClientError\n If:\n - No servers are defined and base_url is not provided\n - OpenAPI spec has no paths\n - An operation is missing operationId\n - Duplicate operationIds are detected\n - Required path parameters are missing\n - Required request body is missing\n\n Example\n-------\n```python\nfrom openapi_first import loader, client\n\nspec = loader.load_openapi(\"openapi.yaml\")\n\napi = client.OpenAPIClient(\n spec=spec,\n base_url=\"http://localhost:8000\",\n)\n\n# Call operationId: getUser\nresponse = api.getUser(\n path_params={\"user_id\": 123}\n)\n\nprint(response.status_code)\nprint(response.json())\n\n# Call operationId: createUser\nresponse = api.createUser(\n body={\"name\": \"Bob\"}\n)\n\nprint(response.status_code)\n```", + "docstring": "OpenAPI-first HTTP client (httpx-based).\n\nNotes:\n **Responsibilities:**\n\n - This client derives all callable methods directly from an OpenAPI 3.x specification. Each operationId becomes a method on the client instance.\n\n **Guarantees:**\n\n - One callable per operationId\n - Explicit parameters (path, query, headers, body)\n - No implicit schema inference or mutation\n - Returns raw `httpx.Response` objects\n - No response validation or deserialization\n\nExample:\n ```python\n from openapi_first import loader, client\n\n spec = loader.load_openapi(\"openapi.yaml\")\n\n api = client.OpenAPIClient(\n spec=spec,\n base_url=\"http://localhost:8000\",\n )\n\n # Call operationId: getUser\n response = api.getUser(\n path_params={\"user_id\": 123}\n )\n\n print(response.status_code)\n print(response.json())\n ```", "members": { "spec": { "name": "spec", diff --git a/mcp_docs/modules/openapi_first.templates.model_app.main.json b/mcp_docs/modules/openapi_first.templates.model_app.main.json index d421e0d..a316930 100644 --- a/mcp_docs/modules/openapi_first.templates.model_app.main.json +++ b/mcp_docs/modules/openapi_first.templates.model_app.main.json @@ -9,7 +9,7 @@ "kind": "class", "path": "openapi_first.templates.model_app.main.OpenAPIFirstApp", "signature": "", - "docstring": "FastAPI application enforcing OpenAPI-first design.\n\n`OpenAPIFirstApp` subclasses FastAPI and replaces manual route\nregistration with OpenAPI-driven binding. All routes are derived\nfrom the provided OpenAPI specification, and each operationId is\nmapped to a Python function in the supplied routes module.\n\nParameters\n----------\nopenapi_path : str\n Filesystem path to the OpenAPI 3.x specification file.\n This specification is treated as the authoritative API contract.\n\nroutes_module : module\n Python module containing handler functions whose names correspond\n exactly to OpenAPI operationId values.\n\n**fastapi_kwargs\n Additional keyword arguments passed directly to `fastapi.FastAPI`\n (e.g., title, version, middleware, lifespan handlers).\n\nRaises\n------\nOpenAPIFirstError\n If the OpenAPI specification is invalid, or if any declared\n operationId does not have a corresponding handler function.\n\nBehavior 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-------\n```python\nfrom openapi_first import OpenAPIFirstApp\nimport app.routes as routes\n\napp = OpenAPIFirstApp(\n openapi_path=\"app/openapi.json\",\n routes_module=routes,\n title=\"Example Service\",\n)\n```", + "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", diff --git a/mcp_docs/modules/openapi_first.templates.model_app.test_model_app.json b/mcp_docs/modules/openapi_first.templates.model_app.test_model_app.json index 43996ce..7232e80 100644 --- a/mcp_docs/modules/openapi_first.templates.model_app.test_model_app.json +++ b/mcp_docs/modules/openapi_first.templates.model_app.test_model_app.json @@ -23,14 +23,14 @@ "kind": "function", "path": "openapi_first.templates.model_app.test_model_app.load_openapi", "signature": "", - "docstring": "Load and validate an OpenAPI 3.x specification from disk.\n\nThe specification is parsed based on file extension and validated\nusing a strict OpenAPI schema validator. Any error results in an\nimmediate exception, preventing application startup.\n\nParameters\n----------\npath : str or pathlib.Path\n Filesystem path to an OpenAPI specification file.\n Supported extensions:\n - `.json`\n - `.yaml`\n - `.yml`\n\nReturns\n-------\ndict\n Parsed and validated OpenAPI specification.\n\nRaises\n------\nOpenAPISpecLoadError\n If the file does not exist, cannot be parsed, or fails\n OpenAPI schema validation." + "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" }, "OpenAPIClient": { "name": "OpenAPIClient", "kind": "class", "path": "openapi_first.templates.model_app.test_model_app.OpenAPIClient", "signature": "", - "docstring": "OpenAPI-first HTTP client (httpx-based).\n\nThis client derives all callable methods directly from an OpenAPI 3.x\nspecification. Each operationId becomes a method on the client\ninstance.\n\nDesign principles\n-----------------\n- One callable per operationId\n- Explicit parameters (path, query, headers, body)\n- No implicit schema inference or mutation\n- Returns raw httpx.Response objects\n- No response validation or deserialization\n\nParameters\n----------\nspec : dict\n Parsed OpenAPI 3.x specification.\nbase_url : str | None\n Base URL of the target service. If omitted, the first entry\n in the OpenAPI `servers` list is used.\nclient : httpx.Client | None\n Optional preconfigured httpx client instance.\n\nRaises\n------\nOpenAPIClientError\n If:\n - No servers are defined and base_url is not provided\n - OpenAPI spec has no paths\n - An operation is missing operationId\n - Duplicate operationIds are detected\n - Required path parameters are missing\n - Required request body is missing\n\n Example\n-------\n```python\nfrom openapi_first import loader, client\n\nspec = loader.load_openapi(\"openapi.yaml\")\n\napi = client.OpenAPIClient(\n spec=spec,\n base_url=\"http://localhost:8000\",\n)\n\n# Call operationId: getUser\nresponse = api.getUser(\n path_params={\"user_id\": 123}\n)\n\nprint(response.status_code)\nprint(response.json())\n\n# Call operationId: createUser\nresponse = api.createUser(\n body={\"name\": \"Bob\"}\n)\n\nprint(response.status_code)\n```", + "docstring": "OpenAPI-first HTTP client (httpx-based).\n\nNotes:\n **Responsibilities:**\n\n - This client derives all callable methods directly from an OpenAPI 3.x specification. Each operationId becomes a method on the client instance.\n\n **Guarantees:**\n\n - One callable per operationId\n - Explicit parameters (path, query, headers, body)\n - No implicit schema inference or mutation\n - Returns raw `httpx.Response` objects\n - No response validation or deserialization\n\nExample:\n ```python\n from openapi_first import loader, client\n\n spec = loader.load_openapi(\"openapi.yaml\")\n\n api = client.OpenAPIClient(\n spec=spec,\n base_url=\"http://localhost:8000\",\n )\n\n # Call operationId: getUser\n response = api.getUser(\n path_params={\"user_id\": 123}\n )\n\n print(response.status_code)\n print(response.json())\n ```", "members": { "spec": { "name": "spec", diff --git a/mkdocs.yml b/mkdocs.yml index 4cba7a1..95167d7 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -8,12 +8,19 @@ theme: text: Inter code: JetBrains Mono features: - - navigation.tabs + - navigation.sections - navigation.expand - navigation.top - navigation.instant + - navigation.tracking + - navigation.indexes - content.code.copy - content.code.annotate + - content.tabs.link + - content.action.edit + - search.highlight + - search.share + - search.suggest plugins: - search - mkdocstrings: @@ -31,6 +38,30 @@ plugins: annotations_path: brief show_root_heading: true group_by_category: true + show_category_heading: true + show_object_full_path: false + show_symbol_type_heading: true +markdown_extensions: +- pymdownx.superfences +- pymdownx.inlinehilite +- pymdownx.snippets +- admonition +- pymdownx.details +- pymdownx.superfences +- pymdownx.highlight: + linenums: true + anchor_linenums: true + line_spans: __span + pygments_lang_class: true +- pymdownx.tabbed: + alternate_style: true +- pymdownx.tasklist: + custom_checkbox: true +- tables +- footnotes +- pymdownx.caret +- pymdownx.tilde +- pymdownx.mark site_name: openapi_first nav: - Home: index.md