using doc-forge (#1)
Reviewed-on: #1 Co-authored-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com> Co-committed-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com>
This commit is contained in:
64
mcp_docs/modules/openapi_first.templates.health_app.json
Normal file
64
mcp_docs/modules/openapi_first.templates.health_app.json
Normal file
@@ -0,0 +1,64 @@
|
||||
{
|
||||
"module": "openapi_first.templates.health_app",
|
||||
"content": {
|
||||
"path": "openapi_first.templates.health_app",
|
||||
"docstring": "OpenAPI-first FastAPI application template.\n\nThis package contains a minimal, fully working example of an\nOpenAPI-first FastAPI service built using the ``openapi_first`` library.\n\nThe application is assembled exclusively from:\n- an OpenAPI specification (``openapi.yaml``)\n- a handler namespace (``routes``)\n\nNo routing decorators, implicit behavior, or framework-specific\nconvenience abstractions are used. All HTTP routes, methods, and\noperation bindings are defined in OpenAPI and enforced at application\nstartup.\n\nThis package is intended to be copied as a starting point for new\nservices via the ``openapi-first`` CLI. It is not part of the\n``openapi_first`` library API surface.\n\n----------------------------------------------------------------------\nScaffolding via CLI\n----------------------------------------------------------------------\n\nCreate a new OpenAPI-first health check service using the bundled\ntemplate:\n\n openapi-first health_app\n\nCreate the service in a custom directory:\n\n openapi-first health_app my-health-service\n\nList all available application templates:\n\n openapi-first --list\n\nThe CLI copies template files verbatim into the target directory.\nNo code is generated or modified beyond the copied scaffold.\n\n----------------------------------------------------------------------\nClient Usage Example\n----------------------------------------------------------------------\n\nThe same OpenAPI specification used by the server can be used to\nconstruct a strict, operationId-driven HTTP client.\n\nExample client call for the ``get_health`` operation:\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 assert response.status_code == 200\n assert response.json() == {\"status\": \"ok\"}\n\nClient guarantees:\n- One callable per OpenAPI ``operationId``\n- No hardcoded URLs or HTTP methods in user code\n- Path and request parameters must match the OpenAPI specification\n- Invalid or incomplete OpenAPI specs fail at client construction time",
|
||||
"objects": {
|
||||
"main": {
|
||||
"name": "main",
|
||||
"kind": "module",
|
||||
"path": "openapi_first.templates.health_app.main",
|
||||
"signature": null,
|
||||
"docstring": "Application entry point for an OpenAPI-first FastAPI service.\n\nThis module constructs a FastAPI application exclusively from an\nOpenAPI specification and a handler namespace, without using\ndecorator-driven routing.\n\nAll HTTP routes, methods, and operation bindings are defined in the\nOpenAPI document referenced by ``openapi_path``. Python callables\ndefined in the ``routes`` module are bound to OpenAPI operations\nstrictly via ``operationId``.\n\nThis module contains no routing logic, request handling, or framework\nconfiguration beyond application assembly.\n\nDesign guarantees:\n- OpenAPI is the single source of truth\n- No undocumented routes can exist\n- Every OpenAPI operationId must resolve to exactly one handler\n- All contract violations fail at application startup\n\nThis file is intended to be used as the ASGI entry point.\n\nExample:\n uvicorn main:app",
|
||||
"members": {
|
||||
"OpenAPIFirstApp": {
|
||||
"name": "OpenAPIFirstApp",
|
||||
"kind": "class",
|
||||
"path": "openapi_first.templates.health_app.main.OpenAPIFirstApp",
|
||||
"signature": "<bound method Alias.signature of Alias('OpenAPIFirstApp', 'openapi_first.app.OpenAPIFirstApp')>",
|
||||
"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... )",
|
||||
"members": {
|
||||
"openapi": {
|
||||
"name": "openapi",
|
||||
"kind": "attribute",
|
||||
"path": "openapi_first.templates.health_app.main.OpenAPIFirstApp.openapi",
|
||||
"signature": "<bound method Alias.signature of Alias('openapi', 'openapi_first.app.OpenAPIFirstApp.openapi')>",
|
||||
"docstring": null
|
||||
}
|
||||
}
|
||||
},
|
||||
"routes": {
|
||||
"name": "routes",
|
||||
"kind": "alias",
|
||||
"path": "openapi_first.templates.health_app.main.routes",
|
||||
"signature": "<bound method Alias.signature of Alias('routes', 'routes')>",
|
||||
"docstring": null
|
||||
},
|
||||
"app": {
|
||||
"name": "app",
|
||||
"kind": "attribute",
|
||||
"path": "openapi_first.templates.health_app.main.app",
|
||||
"signature": null,
|
||||
"docstring": null
|
||||
}
|
||||
}
|
||||
},
|
||||
"routes": {
|
||||
"name": "routes",
|
||||
"kind": "module",
|
||||
"path": "openapi_first.templates.health_app.routes",
|
||||
"signature": null,
|
||||
"docstring": "OpenAPI operation handlers.\n\nThis module defines pure Python callables that implement OpenAPI\noperations for this service. Functions in this module are bound to HTTP\nroutes exclusively via OpenAPI ``operationId`` values.\n\nNo routing decorators, HTTP metadata, or framework-specific logic\nshould appear here. All request/response semantics are defined in the\nOpenAPI specification.\n\nThis module serves solely as an operationId namespace.",
|
||||
"members": {
|
||||
"get_health": {
|
||||
"name": "get_health",
|
||||
"kind": "function",
|
||||
"path": "openapi_first.templates.health_app.routes.get_health",
|
||||
"signature": "<bound method Function.signature of Function('get_health', 16, 32)>",
|
||||
"docstring": "Health check operation handler.\n\nThis function implements the OpenAPI operation identified by\n``operationId: get_health``.\n\nIt contains no routing metadata or framework-specific logic.\nRequest binding, HTTP method, and response semantics are defined\nexclusively by the OpenAPI specification.\n\nReturns\n-------\ndict\n A minimal liveness payload indicating service health."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user