Vishesh 'ironeagle' Bangotra
6bafa435f1
Reviewed-on: #1 Co-authored-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com> Co-committed-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com>
273 lines
22 KiB
JSON
273 lines
22 KiB
JSON
{
|
|
"module": "openapi_first.templates.crud_app",
|
|
"content": {
|
|
"path": "openapi_first.templates.crud_app",
|
|
"docstring": "OpenAPI-first CRUD application template.\n\nThis package contains a complete, minimal example of an OpenAPI-first\nCRUD service built using the ``openapi_first`` library.\n\nThe application is assembled exclusively from:\n- an OpenAPI specification (``openapi.yaml``)\n- a handler namespace implementing CRUD operations (``routes``)\n- an in-memory mock data store (``data``)\n\nAll HTTP routes, methods, schemas, and operation bindings are defined\nin the OpenAPI specification and enforced at application startup.\nNo decorator-driven routing or implicit framework behavior is used.\n\nThis template demonstrates:\n- operationId-driven server-side route binding\n- explicit HTTP status code control in handlers\n- operationId-driven client usage against the same OpenAPI contract\n- end-to-end validation using in-memory data and tests\n\n----------------------------------------------------------------------\nScaffolding via CLI\n----------------------------------------------------------------------\n\nCreate a new CRUD example service using the bundled template:\n\n openapi-first crud_app\n\nCreate the service in a custom directory:\n\n openapi-first crud_app my-crud-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 calls for CRUD operations:\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 # List items\n response = client.list_items()\n\n # Get item by ID\n response = client.get_item(\n path_params={\"item_id\": 1}\n )\n\n # Create item\n response = client.create_item(\n body={\"name\": \"Orange\", \"price\": 0.8}\n )\n\n # Update item\n response = client.update_item(\n path_params={\"item_id\": 1},\n body={\"name\": \"Green Apple\", \"price\": 0.6},\n )\n\n # Delete item\n response = client.delete_item(\n path_params={\"item_id\": 1}\n )\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\n\n----------------------------------------------------------------------\nNon-Goals\n----------------------------------------------------------------------\n\nThis template is intentionally minimal and is NOT:\n- production-ready\n- persistent or concurrency-safe\n- a reference architecture for data storage\n\nIt exists solely as a copyable example for learning, testing, and\nbootstrapping OpenAPI-first services.\n\nThis package is not part of the ``openapi_first`` library API surface.",
|
|
"objects": {
|
|
"data": {
|
|
"name": "data",
|
|
"kind": "module",
|
|
"path": "openapi_first.templates.crud_app.data",
|
|
"signature": null,
|
|
"docstring": "In-memory mock data store for CRUD example.\n\nThis module intentionally avoids persistence and concurrency guarantees.\nIt is suitable for demos, tests, and scaffolding only.\n\nIt intentionally avoids\n- persistence\n- concurrency guarantees\n- validation\n- error handling\n\nThe implementation is suitable for:\n- demonstrations\n- tests\n- scaffolding and example services\n\nIt is explicitly NOT suitable for production use.\n\nThis module is not part of the ``openapi_first`` library API surface.",
|
|
"members": {
|
|
"Dict": {
|
|
"name": "Dict",
|
|
"kind": "alias",
|
|
"path": "openapi_first.templates.crud_app.data.Dict",
|
|
"signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
|
|
"docstring": null
|
|
},
|
|
"list_items": {
|
|
"name": "list_items",
|
|
"kind": "function",
|
|
"path": "openapi_first.templates.crud_app.data.list_items",
|
|
"signature": "<bound method Function.signature of Function('list_items', 36, 48)>",
|
|
"docstring": "Return all items in the data store.\n\nThis function performs no filtering, pagination, or sorting.\nThe returned collection reflects the current in-memory state.\n\nReturns\n-------\nlist[dict]\n A list of item representations."
|
|
},
|
|
"get_item": {
|
|
"name": "get_item",
|
|
"kind": "function",
|
|
"path": "openapi_first.templates.crud_app.data.get_item",
|
|
"signature": "<bound method Function.signature of Function('get_item', 51, 68)>",
|
|
"docstring": "Retrieve a single item by ID.\n\nThis function assumes the item exists and will raise ``KeyError``\nif the ID is not present in the store.\n\nParameters\n----------\nitem_id : int\n Identifier of the item to retrieve.\n\nReturns\n-------\ndict\n The stored item representation."
|
|
},
|
|
"create_item": {
|
|
"name": "create_item",
|
|
"kind": "function",
|
|
"path": "openapi_first.templates.crud_app.data.create_item",
|
|
"signature": "<bound method Function.signature of Function('create_item', 71, 92)>",
|
|
"docstring": "Create a new item in the data store.\n\nA new integer ID is assigned automatically. No validation is\nperformed on the provided payload.\n\nParameters\n----------\npayload : dict\n Item attributes excluding the ``id`` field.\n\nReturns\n-------\ndict\n The newly created item, including its assigned ID."
|
|
},
|
|
"update_item": {
|
|
"name": "update_item",
|
|
"kind": "function",
|
|
"path": "openapi_first.templates.crud_app.data.update_item",
|
|
"signature": "<bound method Function.signature of Function('update_item', 95, 117)>",
|
|
"docstring": "Replace an existing item in the data store.\n\nThis function overwrites the existing item entirely and does not\nperform partial updates or validation. If the item does not exist,\nit will be created implicitly.\n\nParameters\n----------\nitem_id : int\n Identifier of the item to update.\npayload : dict\n Item attributes excluding the ``id`` field.\n\nReturns\n-------\ndict\n The updated item representation."
|
|
},
|
|
"delete_item": {
|
|
"name": "delete_item",
|
|
"kind": "function",
|
|
"path": "openapi_first.templates.crud_app.data.delete_item",
|
|
"signature": "<bound method Function.signature of Function('delete_item', 120, 132)>",
|
|
"docstring": "Remove an item from the data store.\n\nThis function assumes the item exists and will raise ``KeyError``\nif the ID is not present.\n\nParameters\n----------\nitem_id : int\n Identifier of the item to delete."
|
|
}
|
|
}
|
|
},
|
|
"main": {
|
|
"name": "main",
|
|
"kind": "module",
|
|
"path": "openapi_first.templates.crud_app.main",
|
|
"signature": null,
|
|
"docstring": "Application entry point for an OpenAPI-first CRUD example 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, request/response schemas, and operation\nbindings are defined in the OpenAPI document referenced by\n``openapi_path``. Python callables defined in the ``routes`` module are\nbound to OpenAPI operations strictly via ``operationId``.\n\nThis module contains no routing logic, persistence concerns, or\nframework configuration 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.crud_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.crud_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.crud_app.main.routes",
|
|
"signature": "<bound method Alias.signature of Alias('routes', 'routes')>",
|
|
"docstring": null
|
|
},
|
|
"app": {
|
|
"name": "app",
|
|
"kind": "attribute",
|
|
"path": "openapi_first.templates.crud_app.main.app",
|
|
"signature": null,
|
|
"docstring": null
|
|
}
|
|
}
|
|
},
|
|
"routes": {
|
|
"name": "routes",
|
|
"kind": "module",
|
|
"path": "openapi_first.templates.crud_app.routes",
|
|
"signature": null,
|
|
"docstring": "CRUD route handlers bound via OpenAPI operationId.\n\nThese handlers explicitly control HTTP status codes to ensure\nruntime behavior matches the OpenAPI contract.\n\nThis module defines OpenAPI-bound operation handlers for a simple CRUD\nservice. Functions in this module are bound to HTTP routes exclusively\nvia OpenAPI ``operationId`` values.\n\nHandlers explicitly control HTTP response status codes to ensure runtime\nbehavior matches the OpenAPI contract. Error conditions are translated\ninto explicit HTTP responses rather than relying on implicit framework\nbehavior.\n\nNo routing decorators or path definitions appear in this module. All\nrouting, HTTP methods, and schemas are defined in the OpenAPI\nspecification.",
|
|
"members": {
|
|
"Response": {
|
|
"name": "Response",
|
|
"kind": "alias",
|
|
"path": "openapi_first.templates.crud_app.routes.Response",
|
|
"signature": "<bound method Alias.signature of Alias('Response', 'fastapi.Response')>",
|
|
"docstring": null
|
|
},
|
|
"HTTPException": {
|
|
"name": "HTTPException",
|
|
"kind": "alias",
|
|
"path": "openapi_first.templates.crud_app.routes.HTTPException",
|
|
"signature": "<bound method Alias.signature of Alias('HTTPException', 'fastapi.HTTPException')>",
|
|
"docstring": null
|
|
},
|
|
"list_items": {
|
|
"name": "list_items",
|
|
"kind": "function",
|
|
"path": "openapi_first.templates.crud_app.routes.list_items",
|
|
"signature": "<bound method Function.signature of Function('list_items', 32, 44)>",
|
|
"docstring": "List all items.\n\nImplements the OpenAPI operation identified by\n``operationId: list_items``.\n\nReturns\n-------\nlist[dict]\n A list of item representations."
|
|
},
|
|
"get_item": {
|
|
"name": "get_item",
|
|
"kind": "function",
|
|
"path": "openapi_first.templates.crud_app.routes.get_item",
|
|
"signature": "<bound method Function.signature of Function('get_item', 47, 72)>",
|
|
"docstring": "Retrieve a single item by ID.\n\nImplements the OpenAPI operation identified by\n``operationId: get_item``.\n\nParameters\n----------\nitem_id : int\n Identifier of the item to retrieve.\n\nReturns\n-------\ndict\n The requested item.\n\nRaises\n------\nHTTPException\n 404 if the item does not exist."
|
|
},
|
|
"create_item": {
|
|
"name": "create_item",
|
|
"kind": "function",
|
|
"path": "openapi_first.templates.crud_app.routes.create_item",
|
|
"signature": "<bound method Function.signature of Function('create_item', 75, 96)>",
|
|
"docstring": "Create a new item.\n\nImplements the OpenAPI operation identified by\n``operationId: create_item``.\n\nParameters\n----------\npayload : dict\n Item attributes excluding the ``id`` field.\nresponse : fastapi.Response\n Response object used to set the HTTP status code.\n\nReturns\n-------\ndict\n The newly created item."
|
|
},
|
|
"update_item": {
|
|
"name": "update_item",
|
|
"kind": "function",
|
|
"path": "openapi_first.templates.crud_app.routes.update_item",
|
|
"signature": "<bound method Function.signature of Function('update_item', 99, 126)>",
|
|
"docstring": "Update an existing item.\n\nImplements the OpenAPI operation identified by\n``operationId: update_item``.\n\nParameters\n----------\nitem_id : int\n Identifier of the item to update.\npayload : dict\n Item attributes excluding the ``id`` field.\n\nReturns\n-------\ndict\n The updated item.\n\nRaises\n------\nHTTPException\n 404 if the item does not exist."
|
|
},
|
|
"delete_item": {
|
|
"name": "delete_item",
|
|
"kind": "function",
|
|
"path": "openapi_first.templates.crud_app.routes.delete_item",
|
|
"signature": "<bound method Function.signature of Function('delete_item', 129, 158)>",
|
|
"docstring": "Delete an existing item.\n\nImplements the OpenAPI operation identified by\n``operationId: delete_item``.\n\nParameters\n----------\nitem_id : int\n Identifier of the item to delete.\nresponse : fastapi.Response\n Response object used to set the HTTP status code.\n\nReturns\n-------\nNone\n No content.\n\nRaises\n------\nHTTPException\n 404 if the item does not exist."
|
|
}
|
|
}
|
|
},
|
|
"test_crud_app": {
|
|
"name": "test_crud_app",
|
|
"kind": "module",
|
|
"path": "openapi_first.templates.crud_app.test_crud_app",
|
|
"signature": null,
|
|
"docstring": "End-to-end tests for the OpenAPI-first CRUD example app.\n\nThese tests validate that all CRUD operations behave correctly\nagainst the in-memory mock data store.\n- OpenAPI specification loading\n- OperationId-driven route binding on the server\n- OperationId-driven client invocation\n- Correct HTTP status codes and response payloads\n\nThe tests exercise all CRUD operations against an in-memory mock data\nstore and assume deterministic behavior within a single process.\n\nThe tests assume:\n- OpenAPI-first route binding\n- In-memory storage (no persistence guarantees)\n- Deterministic behavior in a single process\n- One-to-one correspondence between OpenAPI operationId values and\n server/client callables",
|
|
"members": {
|
|
"TestClient": {
|
|
"name": "TestClient",
|
|
"kind": "alias",
|
|
"path": "openapi_first.templates.crud_app.test_crud_app.TestClient",
|
|
"signature": "<bound method Alias.signature of Alias('TestClient', 'fastapi.testclient.TestClient')>",
|
|
"docstring": null
|
|
},
|
|
"app": {
|
|
"name": "app",
|
|
"kind": "alias",
|
|
"path": "openapi_first.templates.crud_app.test_crud_app.app",
|
|
"signature": "<bound method Alias.signature of Alias('app', 'main.app')>",
|
|
"docstring": null
|
|
},
|
|
"load_openapi": {
|
|
"name": "load_openapi",
|
|
"kind": "function",
|
|
"path": "openapi_first.templates.crud_app.test_crud_app.load_openapi",
|
|
"signature": "<bound method Alias.signature of Alias('load_openapi', 'openapi_first.loader.load_openapi')>",
|
|
"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."
|
|
},
|
|
"OpenAPIClient": {
|
|
"name": "OpenAPIClient",
|
|
"kind": "class",
|
|
"path": "openapi_first.templates.crud_app.test_crud_app.OpenAPIClient",
|
|
"signature": "<bound method Alias.signature of Alias('OpenAPIClient', 'openapi_first.client.OpenAPIClient')>",
|
|
"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",
|
|
"members": {
|
|
"spec": {
|
|
"name": "spec",
|
|
"kind": "attribute",
|
|
"path": "openapi_first.templates.crud_app.test_crud_app.OpenAPIClient.spec",
|
|
"signature": "<bound method Alias.signature of Alias('spec', 'openapi_first.client.OpenAPIClient.spec')>",
|
|
"docstring": null
|
|
},
|
|
"base_url": {
|
|
"name": "base_url",
|
|
"kind": "attribute",
|
|
"path": "openapi_first.templates.crud_app.test_crud_app.OpenAPIClient.base_url",
|
|
"signature": "<bound method Alias.signature of Alias('base_url', 'openapi_first.client.OpenAPIClient.base_url')>",
|
|
"docstring": null
|
|
},
|
|
"client": {
|
|
"name": "client",
|
|
"kind": "attribute",
|
|
"path": "openapi_first.templates.crud_app.test_crud_app.OpenAPIClient.client",
|
|
"signature": "<bound method Alias.signature of Alias('client', 'openapi_first.client.OpenAPIClient.client')>",
|
|
"docstring": null
|
|
},
|
|
"operations": {
|
|
"name": "operations",
|
|
"kind": "function",
|
|
"path": "openapi_first.templates.crud_app.test_crud_app.OpenAPIClient.operations",
|
|
"signature": "<bound method Alias.signature of Alias('operations', 'openapi_first.client.OpenAPIClient.operations')>",
|
|
"docstring": null
|
|
}
|
|
}
|
|
},
|
|
"client": {
|
|
"name": "client",
|
|
"kind": "attribute",
|
|
"path": "openapi_first.templates.crud_app.test_crud_app.client",
|
|
"signature": null,
|
|
"docstring": null
|
|
},
|
|
"spec": {
|
|
"name": "spec",
|
|
"kind": "attribute",
|
|
"path": "openapi_first.templates.crud_app.test_crud_app.spec",
|
|
"signature": null,
|
|
"docstring": null
|
|
},
|
|
"test_list_items_initial": {
|
|
"name": "test_list_items_initial",
|
|
"kind": "function",
|
|
"path": "openapi_first.templates.crud_app.test_crud_app.test_list_items_initial",
|
|
"signature": "<bound method Function.signature of Function('test_list_items_initial', 38, 49)>",
|
|
"docstring": "Initial items should be present."
|
|
},
|
|
"test_get_item": {
|
|
"name": "test_get_item",
|
|
"kind": "function",
|
|
"path": "openapi_first.templates.crud_app.test_crud_app.test_get_item",
|
|
"signature": "<bound method Function.signature of Function('test_get_item', 52, 62)>",
|
|
"docstring": "Existing item should be retrievable by ID."
|
|
},
|
|
"test_create_item": {
|
|
"name": "test_create_item",
|
|
"kind": "function",
|
|
"path": "openapi_first.templates.crud_app.test_crud_app.test_create_item",
|
|
"signature": "<bound method Function.signature of Function('test_create_item', 65, 85)>",
|
|
"docstring": "Creating a new item should return the created entity."
|
|
},
|
|
"test_update_item": {
|
|
"name": "test_update_item",
|
|
"kind": "function",
|
|
"path": "openapi_first.templates.crud_app.test_crud_app.test_update_item",
|
|
"signature": "<bound method Function.signature of Function('test_update_item', 88, 112)>",
|
|
"docstring": "Updating an item should replace its values."
|
|
},
|
|
"test_delete_item": {
|
|
"name": "test_delete_item",
|
|
"kind": "function",
|
|
"path": "openapi_first.templates.crud_app.test_crud_app.test_delete_item",
|
|
"signature": "<bound method Function.signature of Function('test_delete_item', 115, 125)>",
|
|
"docstring": "Deleting an item should remove it from the store."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
} |