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

fixing examples and adding doc strings

Browse Source
This commit is contained in:
Vishesh 'ironeagle' Bangotra
2026-02-22 13:17:40 +05:30
parent 14ed19d2d5
commit 37b892f695
14 changed files with 159 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
mcp_docs/modules/openapi_first.client.json
View File

@@ -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": "<bound method Class.signature of Class('OpenAPIClientError', 9, 10)>",
"signature": "<bound method Class.signature of Class('OpenAPIClientError', 67, 68)>",
"docstring": "Raised when an OpenAPI client operation fails."
},
"OpenAPIClient": {
"name": "OpenAPIClient",
"kind": "class",
"path": "openapi_first.client.OpenAPIClient",
"signature": "<bound method Class.signature of Class('OpenAPIClient', 13, 176)>",
"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": "<bound method Class.signature of Class('OpenAPIClient', 71, 291)>",
"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": "<bound method Function.signature of Function('operations', 45, 46)>",
"signature": "<bound method Function.signature of Function('operations', 160, 161)>",
"docstring": null
}
}