From 37b892f6950dba0a184e4cb2b45bcd3aaea4b8e5 Mon Sep 17 00:00:00 2001 From: Vishesh 'ironeagle' Bangotra Date: Sun, 22 Feb 2026 13:17:40 +0530 Subject: [PATCH] fixing examples and adding doc strings --- mcp_docs/modules/openapi_first.app.json | 4 +- mcp_docs/modules/openapi_first.client.json | 10 +- mcp_docs/modules/openapi_first.json | 24 ++-- .../openapi_first.templates.crud_app.json | 4 +- ...openapi_first.templates.crud_app.main.json | 2 +- ...irst.templates.crud_app.test_crud_app.json | 2 +- .../openapi_first.templates.health_app.json | 2 +- ...enapi_first.templates.health_app.main.json | 2 +- mcp_docs/modules/openapi_first.templates.json | 10 +- .../openapi_first.templates.model_app.json | 4 +- ...penapi_first.templates.model_app.main.json | 2 +- ...st.templates.model_app.test_model_app.json | 2 +- openapi_first/app.py | 18 +-- openapi_first/client.py | 115 ++++++++++++++++++ 14 files changed, 159 insertions(+), 42 deletions(-) diff --git a/mcp_docs/modules/openapi_first.app.json b/mcp_docs/modules/openapi_first.app.json index 5d48c02..fc36d93 100644 --- a/mcp_docs/modules/openapi_first.app.json +++ b/mcp_docs/modules/openapi_first.app.json @@ -29,8 +29,8 @@ "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>>> 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... )", + "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```", "members": { "openapi": { "name": "openapi", diff --git a/mcp_docs/modules/openapi_first.client.json b/mcp_docs/modules/openapi_first.client.json index d32d2e2..9edf905 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": 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.", "objects": { "Any": { "name": "Any", @@ -57,15 +57,15 @@ "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\n- One callable per operationId\n- Explicit parameters (path, query, headers, body)\n- No implicit schema inference or mutation", + "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```", "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.json b/mcp_docs/modules/openapi_first.json index 5379fc7..dc6485e 100644 --- a/mcp_docs/modules/openapi_first.json +++ b/mcp_docs/modules/openapi_first.json @@ -36,8 +36,8 @@ "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>>> 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... )", + "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```", "members": { "openapi": { "name": "openapi", @@ -178,7 +178,7 @@ "kind": "module", "path": "openapi_first.client", "signature": null, - "docstring": 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.", "members": { "Any": { "name": "Any", @@ -233,15 +233,15 @@ "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\n- One callable per operationId\n- Explicit parameters (path, query, headers, body)\n- No implicit schema inference or mutation", + "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```", "members": { "spec": { "name": "spec", @@ -268,7 +268,7 @@ "name": "operations", "kind": "function", "path": "openapi_first.client.OpenAPIClient.operations", - "signature": "", + "signature": "", "docstring": null } } @@ -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>>> 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... )", + "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```", "members": { "openapi": { "name": "openapi", @@ -579,7 +579,7 @@ "kind": "class", "path": "openapi_first.templates.crud_app.test_crud_app.OpenAPIClient", "signature": "", - "docstring": "OpenAPI-first HTTP client (httpx-based).\n\n- One callable per operationId\n- Explicit parameters (path, query, headers, body)\n- No implicit schema inference or mutation", + "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```", "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>>> 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... )", + "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```", "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>>> 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... )", + "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```", "members": { "openapi": { "name": "openapi", @@ -999,7 +999,7 @@ "kind": "class", "path": "openapi_first.templates.model_app.test_model_app.OpenAPIClient", "signature": "", - "docstring": "OpenAPI-first HTTP client (httpx-based).\n\n- One callable per operationId\n- Explicit parameters (path, query, headers, body)\n- No implicit schema inference or mutation", + "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```", "members": { "spec": { "name": "spec", diff --git a/mcp_docs/modules/openapi_first.templates.crud_app.json b/mcp_docs/modules/openapi_first.templates.crud_app.json index bd944bc..de58301 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>>> 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... )", + "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```", "members": { "openapi": { "name": "openapi", @@ -185,7 +185,7 @@ "kind": "class", "path": "openapi_first.templates.crud_app.test_crud_app.OpenAPIClient", "signature": "", - "docstring": "OpenAPI-first HTTP client (httpx-based).\n\n- One callable per operationId\n- Explicit parameters (path, query, headers, body)\n- No implicit schema inference or mutation", + "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```", "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 a7a70eb..2cc9fa3 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>>> 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... )", + "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```", "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 4b5bece..7c14f24 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 @@ -30,7 +30,7 @@ "kind": "class", "path": "openapi_first.templates.crud_app.test_crud_app.OpenAPIClient", "signature": "", - "docstring": "OpenAPI-first HTTP client (httpx-based).\n\n- One callable per operationId\n- Explicit parameters (path, query, headers, body)\n- No implicit schema inference or mutation", + "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```", "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 b12f611..3648d6f 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>>> 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... )", + "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```", "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 ff6b213..49785ca 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>>> 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... )", + "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```", "members": { "openapi": { "name": "openapi", diff --git a/mcp_docs/modules/openapi_first.templates.json b/mcp_docs/modules/openapi_first.templates.json index 8efd49c..6511ef0 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>>> 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... )", + "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```", "members": { "openapi": { "name": "openapi", @@ -192,7 +192,7 @@ "kind": "class", "path": "openapi_first.templates.crud_app.test_crud_app.OpenAPIClient", "signature": "", - "docstring": "OpenAPI-first HTTP client (httpx-based).\n\n- One callable per operationId\n- Explicit parameters (path, query, headers, body)\n- No implicit schema inference or mutation", + "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```", "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>>> 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... )", + "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```", "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>>> 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... )", + "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```", "members": { "openapi": { "name": "openapi", @@ -612,7 +612,7 @@ "kind": "class", "path": "openapi_first.templates.model_app.test_model_app.OpenAPIClient", "signature": "", - "docstring": "OpenAPI-first HTTP client (httpx-based).\n\n- One callable per operationId\n- Explicit parameters (path, query, headers, body)\n- No implicit schema inference or mutation", + "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```", "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 34dfbc0..b358d03 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>>> 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... )", + "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```", "members": { "openapi": { "name": "openapi", @@ -268,7 +268,7 @@ "kind": "class", "path": "openapi_first.templates.model_app.test_model_app.OpenAPIClient", "signature": "", - "docstring": "OpenAPI-first HTTP client (httpx-based).\n\n- One callable per operationId\n- Explicit parameters (path, query, headers, body)\n- No implicit schema inference or mutation", + "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```", "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 c7db49e..d421e0d 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>>> 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... )", + "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```", "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 2f3a187..43996ce 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 @@ -30,7 +30,7 @@ "kind": "class", "path": "openapi_first.templates.model_app.test_model_app.OpenAPIClient", "signature": "", - "docstring": "OpenAPI-first HTTP client (httpx-based).\n\n- One callable per operationId\n- Explicit parameters (path, query, headers, body)\n- No implicit schema inference or mutation", + "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```", "members": { "spec": { "name": "spec", diff --git a/openapi_first/app.py b/openapi_first/app.py index f816e09..a27e25b 100644 --- a/openapi_first/app.py +++ b/openapi_first/app.py @@ -84,14 +84,16 @@ class OpenAPIFirstApp(FastAPI): Example ------- - >>> from openapi_first import OpenAPIFirstApp - >>> import app.routes as routes - >>> - >>> app = OpenAPIFirstApp( - ... openapi_path="app/openapi.json", - ... routes_module=routes, - ... title="Example Service" - ... ) + ```python + from openapi_first import OpenAPIFirstApp + import app.routes as routes + + app = OpenAPIFirstApp( + openapi_path="app/openapi.json", + routes_module=routes, + title="Example Service", + ) + ``` """ def __init__( diff --git a/openapi_first/client.py b/openapi_first/client.py index 9697392..3854663 100644 --- a/openapi_first/client.py +++ b/openapi_first/client.py @@ -1,3 +1,61 @@ +""" +openapi_first.client +==================== + +OpenAPI-first HTTP client for contract-driven services. + +This module provides `OpenAPIClient`, a thin, strict HTTP client that +derives all callable operations directly from an OpenAPI 3.x specification. + +It is the client counterpart to `OpenAPIFirstApp`. + +Core principles +--------------- +- The OpenAPI specification is the single source of truth. +- Each operationId becomes a callable Python method. +- No implicit schema mutation or inference. +- No code generation step. +- Minimal abstraction over httpx. + +What this module does +--------------------- +- Parses an OpenAPI 3.x specification. +- Dynamically creates one callable per operationId. +- Enforces presence of: + - servers + - paths + - operationId +- Formats path parameters safely. +- Handles JSON request bodies explicitly. +- Returns raw `httpx.Response` objects. + +What this module does NOT do +---------------------------- +- It does not generate client code. +- It does not validate request/response schemas. +- It does not deserialize responses. +- It does not retry requests. +- It does not implement authentication helpers. +- It does not assume non-2xx responses are failures. + +Intended usage +-------------- +This client is designed for: + +- Service-to-service communication +- Integration testing +- Contract-driven internal SDK usage +- Systems that want OpenAPI-first symmetry with `OpenAPIFirstApp` + +Design constraints +------------------ +- Only the first server in the OpenAPI `servers` list is used if + `base_url` is not explicitly provided. +- Only explicitly declared request bodies are allowed. +- `application/json` is handled natively; other media types are sent as raw content. +- All responses are returned as-is. +""" + from typing import Any, Callable, Dict, Optional from urllib.parse import urljoin @@ -14,9 +72,66 @@ class OpenAPIClient: """ OpenAPI-first HTTP client (httpx-based). + This client derives all callable methods directly from an OpenAPI 3.x + specification. Each operationId becomes a method on the client + instance. + + Design principles + ----------------- - One callable per operationId - Explicit parameters (path, query, headers, body) - No implicit schema inference or mutation + - Returns raw httpx.Response objects + - No response validation or deserialization + + Parameters + ---------- + spec : dict + Parsed OpenAPI 3.x specification. + base_url : str | None + Base URL of the target service. If omitted, the first entry + in the OpenAPI `servers` list is used. + client : httpx.Client | None + Optional preconfigured httpx client instance. + + Raises + ------ + OpenAPIClientError + If: + - No servers are defined and base_url is not provided + - OpenAPI spec has no paths + - An operation is missing operationId + - Duplicate operationIds are detected + - Required path parameters are missing + - Required request body is missing + + Example + ------- + ```python + from openapi_first import loader, client + + spec = loader.load_openapi("openapi.yaml") + + api = client.OpenAPIClient( + spec=spec, + base_url="http://localhost:8000", + ) + + # Call operationId: getUser + response = api.getUser( + path_params={"user_id": 123} + ) + + print(response.status_code) + print(response.json()) + + # Call operationId: createUser + response = api.createUser( + body={"name": "Bob"} + ) + + print(response.status_code) + ``` """ def __init__(