docs/libs/openapi-first/site/search/search_index.json

{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"openapi_first/","title":"Openapi First","text":""},{"location":"openapi_first/#openapi_first","title":"openapi_first","text":"<p>FastAPI OpenAPI First \u2014 strict OpenAPI-first application bootstrap for FastAPI.</p> <p>FastAPI OpenAPI First is a contract-first infrastructure library that enforces OpenAPI as the single source of truth for FastAPI services.</p> <p>The library removes decorator-driven routing and replaces it with deterministic, spec-driven application assembly. Every HTTP route, method, and operation is defined in OpenAPI first and bound to Python handlers explicitly via operationId.</p> <p>The package is intentionally minimal and layered. Each module has a single responsibility and exposes explicit contracts rather than convenience facades.</p>"},{"location":"openapi_first/#openapi_first--architecture-overview","title":"Architecture Overview","text":"<p>The library is structured around four core responsibilities:</p> <ul> <li>loader: load and validate OpenAPI 3.x specifications (JSON/YAML)</li> <li>binder: bind OpenAPI operations to FastAPI routes via operationId</li> <li>app: OpenAPI-first FastAPI application bootstrap</li> <li>client: OpenAPI-first HTTP client driven by the same specification</li> <li>errors: explicit error hierarchy for contract violations</li> </ul> <p>The package root acts as a namespace, not a facade. Consumers are expected to import functionality explicitly from the appropriate module.</p>"},{"location":"openapi_first/#openapi_first--installation","title":"Installation","text":"<p>Install using pip:</p> <pre><code>pip install openapi-first\n</code></pre> <p>Or with Poetry:</p> <pre><code>poetry add openapi-first\n</code></pre> <p>Runtime dependencies are intentionally minimal: - fastapi (server-side) - httpx (client-side) - openapi-spec-validator - pyyaml (optional, for YAML specs)</p> <p>The ASGI server (e.g., uvicorn) is an application-level dependency and is not bundled with this library.</p>"},{"location":"openapi_first/#openapi_first--command-line-interface-scaffolding-templates","title":"Command-Line Interface (Scaffolding, Templates)","text":"<p>FastAPI OpenAPI First ships with a small CLI for bootstrapping OpenAPI-first FastAPI applications from bundled templates.</p> <p>List available application templates:</p> <pre><code>openapi-first --list\n</code></pre> <p>Create a new application using the default template:</p> <pre><code>openapi-first\n</code></pre> <p>Create a new application using a specific template:</p> <pre><code>openapi-first health_app\n</code></pre> <p>Create a new application in a custom directory:</p> <pre><code>openapi-first health_app my-service\n</code></pre> <p>The CLI copies template files verbatim into the target directory. No code is generated or modified beyond the copied scaffold.</p>"},{"location":"openapi_first/#openapi_first--server-side-usage-openapi-fastapi","title":"Server-Side Usage (OpenAPI \u2192 FastAPI)","text":"<p>Minimal OpenAPI-first FastAPI application:</p> <pre><code>from openapi_first import app\nimport my_service.routes as routes\n\napi = app.OpenAPIFirstApp(\n    openapi_path=\"openapi.yaml\",\n    routes_module=routes,\n    title=\"My Service\",\n    version=\"1.0.0\",\n)\n\n# Run with:\n# uvicorn my_service.main:api\n</code></pre> <p>Handler definitions (no decorators):</p> <pre><code>def get_health():\n    return {\"status\": \"ok\"}\n</code></pre> <p>OpenAPI snippet:</p> <pre><code>paths:\n  /health:\n    get:\n      operationId: get_health\n      responses:\n        \"200\":\n          description: OK\n</code></pre> <p>The binder guarantees: - Every OpenAPI operationId has exactly one handler - No undocumented routes exist - All mismatches fail at application startup</p>"},{"location":"openapi_first/#openapi_first--client-side-usage-openapi-http-client","title":"Client-Side Usage (OpenAPI \u2192 HTTP Client)","text":"<p>The same OpenAPI specification can be used to construct a strict, operationId-driven HTTP client.</p> <p>Client construction:</p> <pre><code>from openapi_first.loader import load_openapi\nfrom openapi_first.client import OpenAPIClient\n\nspec = load_openapi(\"openapi.yaml\")\n\nclient = OpenAPIClient(spec)\n</code></pre> <p>Calling operations (operationId is the API):</p> <pre><code>response = client.get_health()\nassert response.status_code == 200\nassert response.json() == {\"status\": \"ok\"}\n</code></pre> <p>Path parameters must match the OpenAPI specification exactly:</p> <pre><code>response = client.get_item(\n    path_params={\"item_id\": 1}\n)\n</code></pre> <p>Request bodies are passed explicitly:</p> <pre><code>response = client.create_item(\n    body={\"name\": \"Orange\", \"price\": 0.8}\n)\n</code></pre> <p>Client guarantees: - One callable per OpenAPI operationId - No hardcoded URLs or HTTP methods in user code - Path and body parameters must match the spec exactly - Invalid or incomplete OpenAPI specs fail at client construction time - No schema inference or mutation is performed</p> <p>The client is transport-level only and returns <code>httpx.Response</code> objects directly. Response interpretation and validation are left to the consumer or higher-level layers.</p>"},{"location":"openapi_first/#openapi_first--extensibility-model","title":"Extensibility Model","text":"<p>FastAPI OpenAPI First is designed to be extended via explicit contracts:</p> <ul> <li>Users MAY extend OpenAPI loading behavior (e.g. multi-file specs)   by wrapping or replacing <code>loader.load_openapi</code></li> <li>Users MAY extend route binding behavior by building on top of   <code>binder.bind_routes</code></li> <li>Users MAY layer additional validation (e.g. signature checks)   without modifying core modules</li> </ul> <p>Users SHOULD NOT rely on FastAPI decorators for routing when using this library. Mixing decorator-driven routes with OpenAPI-first routing defeats the contract guarantees and is explicitly unsupported.</p>"},{"location":"openapi_first/#openapi_first--public-api-surface","title":"Public API Surface","text":"<p>The supported public API consists of the following top-level modules:</p> <ul> <li>openapi_first.app</li> <li>openapi_first.binder</li> <li>openapi_first.loader</li> <li>openapi_first.client</li> <li>openapi_first.errors</li> </ul> <p>Classes and functions should be imported explicitly from these modules. No individual symbols are re-exported at the package root.</p>"},{"location":"openapi_first/#openapi_first--design-guarantees","title":"Design Guarantees","text":"<ul> <li>OpenAPI is the single source of truth</li> <li>No undocumented routes can exist</li> <li>No OpenAPI operation can exist without a handler or client callable</li> <li>All contract violations fail at application startup or client creation</li> <li>No hidden FastAPI magic or implicit behavior</li> <li>Deterministic, testable application assembly</li> <li>CI-friendly failure modes</li> </ul> <p>FastAPI OpenAPI First favors correctness, explicitness, and contract enforcement over convenience shortcuts.</p>"},{"location":"openapi_first/#openapi_first--core-philosophy","title":"Core Philosophy","text":"<p><code>FastAPI OpenAPI First</code> operates on the Contract-as-Code principle:</p> <ol> <li>Spec-Driven Routing: The OpenAPI document is the router. Code only exists to fulfill established contracts.</li> <li>Startup Fail-Fast: Binding mismatches (missing handlers or extra operations) are detected during app initialization, not at runtime.</li> <li>Decoupled Symmetry: The same specification drives both the FastAPI server and the <code>httpx</code>-based client, ensuring type-safe communication.</li> </ol>"},{"location":"openapi_first/#openapi_first--documentation-design","title":"Documentation Design","text":"<p>Follow these \"AI-Native\" docstring principles to maximize developer and agent productivity:</p>"},{"location":"openapi_first/#openapi_first--for-humans","title":"For Humans","text":"<ul> <li>Logical Grouping: Document the Loader, Binder, and Client as distinct infrastructure layers.</li> <li>Spec Snippets: Always include the corresponding OpenAPI YAML/JSON snippet alongside Python examples.</li> </ul>"},{"location":"openapi_first/#openapi_first--for-llms","title":"For LLMs","text":"<ul> <li>Full Path Linking: Refer to cross-module dependencies using their full dotted paths (e.g., <code>openapi_first.loader.load_openapi</code>).</li> <li>Complete Stubs: Maintain high-fidelity <code>.pyi</code> stubs for all public interfaces to provide an optimized machine-context.</li> <li>Traceable Errors: Use specific <code>: description</code> pairs in <code>Raises</code> blocks to allow agents to accurately map errors to spec violations.</li> </ul>"},{"location":"openapi_first/app/","title":"App","text":""},{"location":"openapi_first/app/#openapi_first.app","title":"openapi_first.app","text":""},{"location":"openapi_first/app/#openapi_first.app--openapi_firstapp","title":"openapi_first.app","text":"<p>OpenAPI-first application bootstrap for FastAPI.</p> <p>This module provides <code>OpenAPIFirstApp</code>, a thin but strict abstraction that enforces OpenAPI as the single source of truth for a FastAPI service.</p>"},{"location":"openapi_first/app/#openapi_first.app--core-principles","title":"Core principles","text":"<ul> <li>The OpenAPI specification (JSON or YAML) defines the entire API surface.</li> <li>Every operationId in the OpenAPI spec must have a corresponding   Python handler function.</li> <li>Handlers are plain Python callables (no FastAPI decorators).</li> <li>FastAPI route registration is derived exclusively from the spec.</li> <li>FastAPI's autogenerated OpenAPI schema is fully overridden.</li> </ul>"},{"location":"openapi_first/app/#openapi_first.app--what-this-module-does","title":"What this module does","text":"<ul> <li>Loads and validates an OpenAPI 3.x specification.</li> <li>Dynamically binds HTTP routes to handler functions using operationId.</li> <li>Registers routes with FastAPI at application startup.</li> <li>Ensures runtime behavior matches the OpenAPI contract exactly.</li> </ul>"},{"location":"openapi_first/app/#openapi_first.app--what-this-module-does-not-do","title":"What this module does NOT do","text":"<ul> <li>It does not generate OpenAPI specs.</li> <li>It does not generate client code.</li> <li>It does not introduce a new framework or lifecycle.</li> <li>It does not alter FastAPI dependency injection semantics.</li> </ul>"},{"location":"openapi_first/app/#openapi_first.app--intended-usage","title":"Intended usage","text":"<p>This module is intended for teams that want:</p> <ul> <li>OpenAPI-first API development</li> <li>Strong contract enforcement</li> <li>Minimal FastAPI boilerplate</li> <li>Predictable, CI-friendly failures for spec/implementation drift</li> </ul>"},{"location":"openapi_first/app/#openapi_first.app.OpenAPIFirstApp","title":"OpenAPIFirstApp","text":"<pre><code>OpenAPIFirstApp(*, openapi_path: str, routes_module: Any, **fastapi_kwargs: Any)\n</code></pre> <p>               Bases: <code>FastAPI</code></p> <p>FastAPI application enforcing OpenAPI-first design.</p> <p><code>OpenAPIFirstApp</code> subclasses FastAPI and replaces manual route registration with OpenAPI-driven binding. All routes are derived from the provided OpenAPI specification, and each operationId is mapped to a Python function in the supplied routes module.</p>"},{"location":"openapi_first/app/#openapi_first.app.OpenAPIFirstApp--parameters","title":"Parameters","text":"<p>openapi_path : str     Filesystem path to the OpenAPI 3.x specification file.     This specification is treated as the authoritative API contract.</p> module <p>Python module containing handler functions whose names correspond exactly to OpenAPI operationId values.</p> <p>**fastapi_kwargs     Additional keyword arguments passed directly to <code>fastapi.FastAPI</code>     (e.g., title, version, middleware, lifespan handlers).</p>"},{"location":"openapi_first/app/#openapi_first.app.OpenAPIFirstApp--raises","title":"Raises","text":"<p>OpenAPIFirstError     If the OpenAPI specification is invalid, or if any declared     operationId does not have a corresponding handler function.</p>"},{"location":"openapi_first/app/#openapi_first.app.OpenAPIFirstApp--behavior-guarantees","title":"Behavior guarantees","text":"<ul> <li>No route can exist without an OpenAPI declaration.</li> <li>No OpenAPI operation can exist without a handler.</li> <li>Swagger UI and <code>/openapi.json</code> always reflect the provided spec.</li> <li>Handler functions remain framework-agnostic and testable.</li> </ul>"},{"location":"openapi_first/app/#openapi_first.app.OpenAPIFirstApp--example","title":"Example","text":"<p>from openapi_first import OpenAPIFirstApp import app.routes as routes</p> <p>app = OpenAPIFirstApp( ...     openapi_path=\"app/openapi.json\", ...     routes_module=routes, ...     title=\"Example Service\" ... )</p>"},{"location":"openapi_first/binder/","title":"Binder","text":""},{"location":"openapi_first/binder/#openapi_first.binder","title":"openapi_first.binder","text":""},{"location":"openapi_first/binder/#openapi_first.binder--openapi_firstbinder","title":"openapi_first.binder","text":"<p>OpenAPI-driven route binding for FastAPI.</p> <p>This module is responsible for translating an OpenAPI 3.x specification into concrete FastAPI routes. It enforces a strict one-to-one mapping between OpenAPI operations and Python handler functions using operationId.</p>"},{"location":"openapi_first/binder/#openapi_first.binder--core-responsibility","title":"Core responsibility","text":"<ul> <li>Read path + method definitions from an OpenAPI specification</li> <li>Resolve each operationId to a Python callable</li> <li>Register routes with FastAPI using APIRoute</li> <li>Fail fast when contract violations are detected</li> </ul>"},{"location":"openapi_first/binder/#openapi_first.binder--design-constraints","title":"Design constraints","text":"<ul> <li>All routes MUST be declared in the OpenAPI specification.</li> <li>All OpenAPI operations MUST define an operationId.</li> <li>Every operationId MUST resolve to a handler function.</li> <li>Handlers are plain Python callables (no decorators required).</li> <li>No implicit route creation or inference is allowed.</li> </ul>"},{"location":"openapi_first/binder/#openapi_first.binder--this-module-intentionally-does-not","title":"This module intentionally does NOT:","text":"<ul> <li>Perform request or response validation</li> <li>Generate Pydantic models</li> <li>Modify FastAPI dependency injection</li> <li>Interpret OpenAPI semantics beyond routing metadata</li> </ul> <p>Those concerns belong to other layers or tooling.</p>"},{"location":"openapi_first/binder/#openapi_first.binder.bind_routes","title":"bind_routes","text":"<pre><code>bind_routes(app: FastAPI, spec: Dict[str, Any], routes_module: Any) -&gt; None\n</code></pre> <p>Bind OpenAPI operations to FastAPI routes.</p> <p>Iterates through the OpenAPI specification paths and methods, resolves each operationId to a handler function, and registers a corresponding APIRoute on the FastAPI application.</p>"},{"location":"openapi_first/binder/#openapi_first.binder.bind_routes--parameters","title":"Parameters","text":"<p>app : fastapi.FastAPI     The FastAPI application instance to which routes will be added.</p> dict <p>Parsed OpenAPI 3.x specification dictionary.</p> module <p>Python module containing handler functions. Each handler's name MUST exactly match an OpenAPI operationId.</p>"},{"location":"openapi_first/binder/#openapi_first.binder.bind_routes--raises","title":"Raises","text":"<p>MissingOperationHandler     If an operationId is missing from the spec or if no corresponding     handler function exists in the routes module.</p>"},{"location":"openapi_first/binder/#openapi_first.binder.bind_routes--behavior-guarantees","title":"Behavior guarantees","text":"<ul> <li>Route registration is deterministic and spec-driven.</li> <li>No route decorators are required or supported.</li> <li>Handler resolution errors surface at application startup.</li> </ul>"},{"location":"openapi_first/cli/","title":"Cli","text":""},{"location":"openapi_first/cli/#openapi_first.cli","title":"openapi_first.cli","text":""},{"location":"openapi_first/cli/#openapi_first.cli--openapi_firstcli","title":"openapi_first.cli","text":"<p>Command-line interface for FastAPI OpenAPI-first scaffolding utilities.</p> <p>This CLI bootstraps OpenAPI-first FastAPI applications from versioned, bundled templates packaged with the library.</p>"},{"location":"openapi_first/cli/#openapi_first.cli.available_templates","title":"available_templates","text":"<pre><code>available_templates() -&gt; list[str]\n</code></pre> <p>Return a list of available application templates.</p>"},{"location":"openapi_first/cli/#openapi_first.cli.copy_template","title":"copy_template","text":"<pre><code>copy_template(template: str, target_dir: Path) -&gt; None\n</code></pre> <p>Copy a bundled OpenAPI-first application template into a directory.</p>"},{"location":"openapi_first/client/","title":"Client","text":""},{"location":"openapi_first/client/#openapi_first.client","title":"openapi_first.client","text":""},{"location":"openapi_first/client/#openapi_first.client.OpenAPIClient","title":"OpenAPIClient","text":"<pre><code>OpenAPIClient(spec: Dict[str, Any], base_url: Optional[str] = None, client: Optional[httpx.Client] = None)\n</code></pre> <p>OpenAPI-first HTTP client (httpx-based).</p> <ul> <li>One callable per operationId</li> <li>Explicit parameters (path, query, headers, body)</li> <li>No implicit schema inference or mutation</li> </ul>"},{"location":"openapi_first/client/#openapi_first.client.OpenAPIClientError","title":"OpenAPIClientError","text":"<p>               Bases: <code>OpenAPIFirstError</code></p> <p>Raised when an OpenAPI client operation fails.</p>"},{"location":"openapi_first/errors/","title":"Errors","text":""},{"location":"openapi_first/errors/#openapi_first.errors","title":"openapi_first.errors","text":""},{"location":"openapi_first/errors/#openapi_first.errors--openapi_firsterrors","title":"openapi_first.errors","text":"<p>Custom exceptions for OpenAPI-first FastAPI applications.</p> <p>This module defines a small hierarchy of explicit, intention-revealing exceptions used to signal contract violations between an OpenAPI specification and its Python implementation.</p>"},{"location":"openapi_first/errors/#openapi_first.errors--design-principles","title":"Design principles","text":"<ul> <li>Errors represent programmer mistakes, not runtime conditions.</li> <li>All errors are raised during application startup.</li> <li>Messages are actionable and suitable for CI/CD output.</li> <li>Exceptions are explicit rather than reused from generic built-ins.</li> </ul> <p>These errors should normally cause immediate application failure.</p>"},{"location":"openapi_first/errors/#openapi_first.errors.MissingOperationHandler","title":"MissingOperationHandler","text":"<pre><code>MissingOperationHandler(*, path: str, method: str, operation_id: Optional[str] = None)\n</code></pre> <p>               Bases: <code>OpenAPIFirstError</code></p> <p>Raised when an OpenAPI operation cannot be resolved to a handler.</p> <p>This error occurs when: - An OpenAPI operation does not define an operationId, or - An operationId is defined but no matching function exists in the   provided routes module.</p> <p>This represents a violation of the OpenAPI-first contract and indicates that the specification and implementation are out of sync.</p>"},{"location":"openapi_first/errors/#openapi_first.errors.MissingOperationHandler--parameters","title":"Parameters","text":"<p>path : str     The HTTP path declared in the OpenAPI specification.</p> str <p>The HTTP method (as declared in the OpenAPI spec).</p> str, optional <p>The operationId declared in the OpenAPI spec, if present.</p>"},{"location":"openapi_first/errors/#openapi_first.errors.OpenAPIFirstError","title":"OpenAPIFirstError","text":"<p>               Bases: <code>Exception</code></p> <p>Base exception for all OpenAPI-first enforcement errors.</p> <p>This exception exists to allow callers, test suites, and CI pipelines to catch and distinguish OpenAPI contract violations from unrelated runtime errors.</p> <p>All exceptions raised by the OpenAPI-first core should inherit from this type.</p>"},{"location":"openapi_first/loader/","title":"Loader","text":""},{"location":"openapi_first/loader/#openapi_first.loader","title":"openapi_first.loader","text":""},{"location":"openapi_first/loader/#openapi_first.loader--openapi_firstloaders","title":"openapi_first.loaders","text":"<p>OpenAPI specification loading and validation utilities.</p> <p>This module is responsible for loading an OpenAPI 3.x specification from disk and validating it before it is used by the application.</p> <p>It enforces the principle that an invalid or malformed OpenAPI document must never reach the routing or runtime layers.</p>"},{"location":"openapi_first/loader/#openapi_first.loader--design-principles","title":"Design principles","text":"<ul> <li>OpenAPI is treated as an authoritative contract.</li> <li>Invalid specifications fail fast at application startup.</li> <li>Supported formats are JSON and YAML.</li> <li>Validation errors are surfaced clearly and early.</li> </ul>"},{"location":"openapi_first/loader/#openapi_first.loader--this-module-intentionally-does-not","title":"This module intentionally does NOT:","text":"<ul> <li>Modify the OpenAPI document</li> <li>Infer missing fields</li> <li>Generate models or code</li> <li>Perform request/response validation at runtime</li> </ul>"},{"location":"openapi_first/loader/#openapi_first.loader.OpenAPISpecLoadError","title":"OpenAPISpecLoadError","text":"<p>               Bases: <code>OpenAPIFirstError</code></p> <p>Raised when an OpenAPI specification cannot be loaded or validated.</p> <p>This error indicates that the OpenAPI document is unreadable, malformed, or violates the OpenAPI 3.x specification.</p>"},{"location":"openapi_first/loader/#openapi_first.loader.load_openapi","title":"load_openapi","text":"<pre><code>load_openapi(path: Union[str, Path]) -&gt; Dict[str, Any]\n</code></pre> <p>Load and validate an OpenAPI 3.x specification from disk.</p> <p>The specification is parsed based on file extension and validated using a strict OpenAPI schema validator. Any error results in an immediate exception, preventing application startup.</p>"},{"location":"openapi_first/loader/#openapi_first.loader.load_openapi--parameters","title":"Parameters","text":"<p>path : str or pathlib.Path     Filesystem path to an OpenAPI specification file.     Supported extensions:     - <code>.json</code>     - <code>.yaml</code>     - <code>.yml</code></p>"},{"location":"openapi_first/loader/#openapi_first.loader.load_openapi--returns","title":"Returns","text":"<p>dict     Parsed and validated OpenAPI specification.</p>"},{"location":"openapi_first/loader/#openapi_first.loader.load_openapi--raises","title":"Raises","text":"<p>OpenAPISpecLoadError     If the file does not exist, cannot be parsed, or fails     OpenAPI schema validation.</p>"},{"location":"openapi_first/templates/","title":"Templates","text":""},{"location":"openapi_first/templates/#openapi_first.templates","title":"openapi_first.templates","text":"<p>Application templates for FastAPI OpenAPI First.</p> <p>This package contains example and scaffolding templates intended to be copied into user projects via the <code>openapi-first</code> CLI.</p> <p>Templates in this package are: - Reference implementations of OpenAPI-first services - Not part of the <code>openapi_first</code> public or internal API - Not intended to be imported as runtime dependencies</p> <p>The presence of this file exists solely to: - Mark the directory as an explicit Python package - Enable deterministic tooling behavior (documentation, packaging) - Avoid accidental traversal of non-package directories</p> <p>No code in this package should be imported by library consumers.</p>"},{"location":"openapi_first/templates/crud_app/","title":"Crud App","text":""},{"location":"openapi_first/templates/crud_app/#openapi_first.templates.crud_app","title":"openapi_first.templates.crud_app","text":"<p>OpenAPI-first CRUD application template.</p> <p>This package contains a complete, minimal example of an OpenAPI-first CRUD service built using the <code>openapi_first</code> library.</p> <p>The application is assembled exclusively from: - an OpenAPI specification (<code>openapi.yaml</code>) - a handler namespace implementing CRUD operations (<code>routes</code>) - an in-memory mock data store (<code>data</code>)</p> <p>All HTTP routes, methods, schemas, and operation bindings are defined in the OpenAPI specification and enforced at application startup. No decorator-driven routing or implicit framework behavior is used.</p> <p>This template demonstrates: - operationId-driven server-side route binding - explicit HTTP status code control in handlers - operationId-driven client usage against the same OpenAPI contract - end-to-end validation using in-memory data and tests</p>"},{"location":"openapi_first/templates/crud_app/#openapi_first.templates.crud_app--scaffolding-via-cli","title":"Scaffolding via CLI","text":"<p>Create a new CRUD example service using the bundled template:</p> <pre><code>openapi-first crud_app\n</code></pre> <p>Create the service in a custom directory:</p> <pre><code>openapi-first crud_app my-crud-service\n</code></pre> <p>List all available application templates:</p> <pre><code>openapi-first --list\n</code></pre> <p>The CLI copies template files verbatim into the target directory. No code is generated or modified beyond the copied scaffold.</p>"},{"location":"openapi_first/templates/crud_app/#openapi_first.templates.crud_app--client-usage-example","title":"Client Usage Example","text":"<p>The same OpenAPI specification used by the server can be used to construct a strict, operationId-driven HTTP client.</p> <p>Example client calls for CRUD operations:</p> <pre><code>from openapi_first.loader import load_openapi\nfrom openapi_first.client import OpenAPIClient\n\nspec = load_openapi(\"openapi.yaml\")\nclient = OpenAPIClient(spec)\n\n# List items\nresponse = client.list_items()\n\n# Get item by ID\nresponse = client.get_item(\n    path_params={\"item_id\": 1}\n)\n\n# Create item\nresponse = client.create_item(\n    body={\"name\": \"Orange\", \"price\": 0.8}\n)\n\n# Update item\nresponse = client.update_item(\n    path_params={\"item_id\": 1},\n    body={\"name\": \"Green Apple\", \"price\": 0.6},\n)\n\n# Delete item\nresponse = client.delete_item(\n    path_params={\"item_id\": 1}\n)\n</code></pre> <p>Client guarantees: - One callable per OpenAPI <code>operationId</code> - No hardcoded URLs or HTTP methods in user code - Path and request parameters must match the OpenAPI specification - Invalid or incomplete OpenAPI specs fail at client construction time</p>"},{"location":"openapi_first/templates/crud_app/#openapi_first.templates.crud_app--non-goals","title":"Non-Goals","text":"<p>This template is intentionally minimal and is NOT: - production-ready - persistent or concurrency-safe - a reference architecture for data storage</p> <p>It exists solely as a copyable example for learning, testing, and bootstrapping OpenAPI-first services.</p> <p>This package is not part of the <code>openapi_first</code> library API surface.</p>"},{"location":"openapi_first/templates/crud_app/data/","title":"Data","text":""},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data","title":"openapi_first.templates.crud_app.data","text":"<p>In-memory mock data store for CRUD example.</p> <p>This module intentionally avoids persistence and concurrency guarantees. It is suitable for demos, tests, and scaffolding only.</p> <p>It intentionally avoids - persistence - concurrency guarantees - validation - error handling</p> <p>The implementation is suitable for: - demonstrations - tests - scaffolding and example services</p> <p>It is explicitly NOT suitable for production use.</p> <p>This module is not part of the <code>openapi_first</code> library API surface.</p>"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.create_item","title":"create_item","text":"<pre><code>create_item(payload: dict)\n</code></pre> <p>Create a new item in the data store.</p> <p>A new integer ID is assigned automatically. No validation is performed on the provided payload.</p>"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.create_item--parameters","title":"Parameters","text":"<p>payload : dict     Item attributes excluding the <code>id</code> field.</p>"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.create_item--returns","title":"Returns","text":"<p>dict     The newly created item, including its assigned ID.</p>"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.delete_item","title":"delete_item","text":"<pre><code>delete_item(item_id: int)\n</code></pre> <p>Remove an item from the data store.</p> <p>This function assumes the item exists and will raise <code>KeyError</code> if the ID is not present.</p>"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.delete_item--parameters","title":"Parameters","text":"<p>item_id : int     Identifier of the item to delete.</p>"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.get_item","title":"get_item","text":"<pre><code>get_item(item_id: int)\n</code></pre> <p>Retrieve a single item by ID.</p> <p>This function assumes the item exists and will raise <code>KeyError</code> if the ID is not present in the store.</p>"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.get_item--parameters","title":"Parameters","text":"<p>item_id : int     Identifier of the item to retrieve.</p>"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.get_item--returns","title":"Returns","text":"<p>dict     The stored item representation.</p>"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.list_items","title":"list_items","text":"<pre><code>list_items()\n</code></pre> <p>Return all items in the data store.</p> <p>This function performs no filtering, pagination, or sorting. The returned collection reflects the current in-memory state.</p>"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.list_items--returns","title":"Returns","text":"<p>list[dict]     A list of item representations.</p>"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.update_item","title":"update_item","text":"<pre><code>update_item(item_id: int, payload: dict)\n</code></pre> <p>Replace an existing item in the data store.</p> <p>This function overwrites the existing item entirely and does not perform partial updates or validation. If the item does not exist, it will be created implicitly.</p>"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.update_item--parameters","title":"Parameters","text":"<p>item_id : int     Identifier of the item to update. payload : dict     Item attributes excluding the <code>id</code> field.</p>"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.update_item--returns","title":"Returns","text":"<p>dict     The updated item representation.</p>"},{"location":"openapi_first/templates/crud_app/main/","title":"Main","text":""},{"location":"openapi_first/templates/crud_app/main/#openapi_first.templates.crud_app.main","title":"openapi_first.templates.crud_app.main","text":"<p>Application entry point for an OpenAPI-first CRUD example service.</p> <p>This module constructs a FastAPI application exclusively from an OpenAPI specification and a handler namespace, without using decorator-driven routing.</p> <p>All HTTP routes, methods, request/response schemas, and operation bindings are defined in the OpenAPI document referenced by <code>openapi_path</code>. Python callables defined in the <code>routes</code> module are bound to OpenAPI operations strictly via <code>operationId</code>.</p> <p>This module contains no routing logic, persistence concerns, or framework configuration beyond application assembly.</p> <p>Design guarantees: - OpenAPI is the single source of truth - No undocumented routes can exist - Every OpenAPI operationId must resolve to exactly one handler - All contract violations fail at application startup</p> <p>This file is intended to be used as the ASGI entry point.</p> Example <p>uvicorn main:app</p>"},{"location":"openapi_first/templates/crud_app/routes/","title":"Routes","text":""},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes","title":"openapi_first.templates.crud_app.routes","text":"<p>CRUD route handlers bound via OpenAPI operationId.</p> <p>These handlers explicitly control HTTP status codes to ensure runtime behavior matches the OpenAPI contract.</p> <p>This module defines OpenAPI-bound operation handlers for a simple CRUD service. Functions in this module are bound to HTTP routes exclusively via OpenAPI <code>operationId</code> values.</p> <p>Handlers explicitly control HTTP response status codes to ensure runtime behavior matches the OpenAPI contract. Error conditions are translated into explicit HTTP responses rather than relying on implicit framework behavior.</p> <p>No routing decorators or path definitions appear in this module. All routing, HTTP methods, and schemas are defined in the OpenAPI specification.</p>"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.create_item","title":"create_item","text":"<pre><code>create_item(payload: dict, response: Response)\n</code></pre> <p>Create a new item.</p> <p>Implements the OpenAPI operation identified by <code>operationId: create_item</code>.</p>"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.create_item--parameters","title":"Parameters","text":"<p>payload : dict     Item attributes excluding the <code>id</code> field. response : fastapi.Response     Response object used to set the HTTP status code.</p>"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.create_item--returns","title":"Returns","text":"<p>dict     The newly created item.</p>"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.delete_item","title":"delete_item","text":"<pre><code>delete_item(item_id: int, response: Response)\n</code></pre> <p>Delete an existing item.</p> <p>Implements the OpenAPI operation identified by <code>operationId: delete_item</code>.</p>"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.delete_item--parameters","title":"Parameters","text":"<p>item_id : int     Identifier of the item to delete. response : fastapi.Response     Response object used to set the HTTP status code.</p>"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.delete_item--returns","title":"Returns","text":"<p>None     No content.</p>"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.delete_item--raises","title":"Raises","text":"<p>HTTPException     404 if the item does not exist.</p>"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.get_item","title":"get_item","text":"<pre><code>get_item(item_id: int)\n</code></pre> <p>Retrieve a single item by ID.</p> <p>Implements the OpenAPI operation identified by <code>operationId: get_item</code>.</p>"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.get_item--parameters","title":"Parameters","text":"<p>item_id : int     Identifier of the item to retrieve.</p>"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.get_item--returns","title":"Returns","text":"<p>dict     The requested item.</p>"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.get_item--raises","title":"Raises","text":"<p>HTTPException     404 if the item does not exist.</p>"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.list_items","title":"list_items","text":"<pre><code>list_items()\n</code></pre> <p>List all items.</p> <p>Implements the OpenAPI operation identified by <code>operationId: list_items</code>.</p>"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.list_items--returns","title":"Returns","text":"<p>list[dict]     A list of item representations.</p>"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.update_item","title":"update_item","text":"<pre><code>update_item(item_id: int, payload: dict)\n</code></pre> <p>Update an existing item.</p> <p>Implements the OpenAPI operation identified by <code>operationId: update_item</code>.</p>"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.update_item--parameters","title":"Parameters","text":"<p>item_id : int     Identifier of the item to update. payload : dict     Item attributes excluding the <code>id</code> field.</p>"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.update_item--returns","title":"Returns","text":"<p>dict     The updated item.</p>"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.update_item--raises","title":"Raises","text":"<p>HTTPException     404 if the item does not exist.</p>"},{"location":"openapi_first/templates/crud_app/test_crud_app/","title":"Test Crud App","text":""},{"location":"openapi_first/templates/crud_app/test_crud_app/#openapi_first.templates.crud_app.test_crud_app","title":"openapi_first.templates.crud_app.test_crud_app","text":"<p>End-to-end tests for the OpenAPI-first CRUD example app.</p> <p>These tests validate that all CRUD operations behave correctly against the in-memory mock data store. - OpenAPI specification loading - OperationId-driven route binding on the server - OperationId-driven client invocation - Correct HTTP status codes and response payloads</p> <p>The tests exercise all CRUD operations against an in-memory mock data store and assume deterministic behavior within a single process.</p> <p>The tests assume: - OpenAPI-first route binding - In-memory storage (no persistence guarantees) - Deterministic behavior in a single process - One-to-one correspondence between OpenAPI operationId values and   server/client callables</p>"},{"location":"openapi_first/templates/crud_app/test_crud_app/#openapi_first.templates.crud_app.test_crud_app.test_create_item","title":"test_create_item","text":"<pre><code>test_create_item()\n</code></pre> <p>Creating a new item should return the created entity.</p>"},{"location":"openapi_first/templates/crud_app/test_crud_app/#openapi_first.templates.crud_app.test_crud_app.test_delete_item","title":"test_delete_item","text":"<pre><code>test_delete_item()\n</code></pre> <p>Deleting an item should remove it from the store.</p>"},{"location":"openapi_first/templates/crud_app/test_crud_app/#openapi_first.templates.crud_app.test_crud_app.test_get_item","title":"test_get_item","text":"<pre><code>test_get_item()\n</code></pre> <p>Existing item should be retrievable by ID.</p>"},{"location":"openapi_first/templates/crud_app/test_crud_app/#openapi_first.templates.crud_app.test_crud_app.test_list_items_initial","title":"test_list_items_initial","text":"<pre><code>test_list_items_initial()\n</code></pre> <p>Initial items should be present.</p>"},{"location":"openapi_first/templates/crud_app/test_crud_app/#openapi_first.templates.crud_app.test_crud_app.test_update_item","title":"test_update_item","text":"<pre><code>test_update_item()\n</code></pre> <p>Updating an item should replace its values.</p>"},{"location":"openapi_first/templates/health_app/","title":"Health App","text":""},{"location":"openapi_first/templates/health_app/#openapi_first.templates.health_app","title":"openapi_first.templates.health_app","text":"<p>OpenAPI-first FastAPI application template.</p> <p>This package contains a minimal, fully working example of an OpenAPI-first FastAPI service built using the <code>openapi_first</code> library.</p> <p>The application is assembled exclusively from: - an OpenAPI specification (<code>openapi.yaml</code>) - a handler namespace (<code>routes</code>)</p> <p>No routing decorators, implicit behavior, or framework-specific convenience abstractions are used. All HTTP routes, methods, and operation bindings are defined in OpenAPI and enforced at application startup.</p> <p>This package is intended to be copied as a starting point for new services via the <code>openapi-first</code> CLI. It is not part of the <code>openapi_first</code> library API surface.</p>"},{"location":"openapi_first/templates/health_app/#openapi_first.templates.health_app--scaffolding-via-cli","title":"Scaffolding via CLI","text":"<p>Create a new OpenAPI-first health check service using the bundled template:</p> <pre><code>openapi-first health_app\n</code></pre> <p>Create the service in a custom directory:</p> <pre><code>openapi-first health_app my-health-service\n</code></pre> <p>List all available application templates:</p> <pre><code>openapi-first --list\n</code></pre> <p>The CLI copies template files verbatim into the target directory. No code is generated or modified beyond the copied scaffold.</p>"},{"location":"openapi_first/templates/health_app/#openapi_first.templates.health_app--client-usage-example","title":"Client Usage Example","text":"<p>The same OpenAPI specification used by the server can be used to construct a strict, operationId-driven HTTP client.</p> <p>Example client call for the <code>get_health</code> operation:</p> <pre><code>from openapi_first.loader import load_openapi\nfrom openapi_first.client import OpenAPIClient\n\nspec = load_openapi(\"openapi.yaml\")\nclient = OpenAPIClient(spec)\n\nresponse = client.get_health()\n\nassert response.status_code == 200\nassert response.json() == {\"status\": \"ok\"}\n</code></pre> <p>Client guarantees: - One callable per OpenAPI <code>operationId</code> - No hardcoded URLs or HTTP methods in user code - Path and request parameters must match the OpenAPI specification - Invalid or incomplete OpenAPI specs fail at client construction time</p>"},{"location":"openapi_first/templates/health_app/main/","title":"Main","text":""},{"location":"openapi_first/templates/health_app/main/#openapi_first.templates.health_app.main","title":"openapi_first.templates.health_app.main","text":"<p>Application entry point for an OpenAPI-first FastAPI service.</p> <p>This module constructs a FastAPI application exclusively from an OpenAPI specification and a handler namespace, without using decorator-driven routing.</p> <p>All HTTP routes, methods, and operation bindings are defined in the OpenAPI document referenced by <code>openapi_path</code>. Python callables defined in the <code>routes</code> module are bound to OpenAPI operations strictly via <code>operationId</code>.</p> <p>This module contains no routing logic, request handling, or framework configuration beyond application assembly.</p> <p>Design guarantees: - OpenAPI is the single source of truth - No undocumented routes can exist - Every OpenAPI operationId must resolve to exactly one handler - All contract violations fail at application startup</p> <p>This file is intended to be used as the ASGI entry point.</p> Example <p>uvicorn main:app</p>"},{"location":"openapi_first/templates/health_app/routes/","title":"Routes","text":""},{"location":"openapi_first/templates/health_app/routes/#openapi_first.templates.health_app.routes","title":"openapi_first.templates.health_app.routes","text":"<p>OpenAPI operation handlers.</p> <p>This module defines pure Python callables that implement OpenAPI operations for this service. Functions in this module are bound to HTTP routes exclusively via OpenAPI <code>operationId</code> values.</p> <p>No routing decorators, HTTP metadata, or framework-specific logic should appear here. All request/response semantics are defined in the OpenAPI specification.</p> <p>This module serves solely as an operationId namespace.</p>"},{"location":"openapi_first/templates/health_app/routes/#openapi_first.templates.health_app.routes.get_health","title":"get_health","text":"<pre><code>get_health()\n</code></pre> <p>Health check operation handler.</p> <p>This function implements the OpenAPI operation identified by <code>operationId: get_health</code>.</p> <p>It contains no routing metadata or framework-specific logic. Request binding, HTTP method, and response semantics are defined exclusively by the OpenAPI specification.</p>"},{"location":"openapi_first/templates/health_app/routes/#openapi_first.templates.health_app.routes.get_health--returns","title":"Returns","text":"<p>dict     A minimal liveness payload indicating service health.</p>"},{"location":"openapi_first/templates/model_app/","title":"Model App","text":""},{"location":"openapi_first/templates/model_app/#openapi_first.templates.model_app","title":"openapi_first.templates.model_app","text":"<p>OpenAPI-first model-based CRUD application template.</p> <p>This package contains a complete, minimal example of an OpenAPI-first CRUD service that uses explicit Pydantic domain models for request and response schemas.</p> <p>The application is assembled exclusively from: - an OpenAPI specification (<code>openapi.yaml</code>) - a handler namespace implementing CRUD operations (<code>routes</code>) - Pydantic domain models (<code>models</code>) - an in-memory mock data store (<code>data</code>)</p> <p>All HTTP routes, methods, schemas, and operation bindings are defined in the OpenAPI specification and enforced at application startup. No decorator-driven routing or implicit framework behavior is used.</p> <p>This template demonstrates: - operationId-driven server-side route binding - explicit request and response modeling with Pydantic - explicit HTTP status code control in handlers - operationId-driven client usage against the same OpenAPI contract - end-to-end validation using in-memory data and tests</p>"},{"location":"openapi_first/templates/model_app/#openapi_first.templates.model_app--scaffolding-via-cli","title":"Scaffolding via CLI","text":"<p>Create a new model-based CRUD example service using the bundled template:</p> <pre><code>openapi-first model_app\n</code></pre> <p>Create the service in a custom directory:</p> <pre><code>openapi-first model_app my-model-service\n</code></pre> <p>List all available application templates:</p> <pre><code>openapi-first --list\n</code></pre> <p>The CLI copies template files verbatim into the target directory. No code is generated or modified beyond the copied scaffold.</p>"},{"location":"openapi_first/templates/model_app/#openapi_first.templates.model_app--client-usage-example","title":"Client Usage Example","text":"<p>The same OpenAPI specification used by the server can be used to construct a strict, operationId-driven HTTP client.</p> <p>Example client calls for model-based CRUD operations:</p> <pre><code>from openapi_first.loader import load_openapi\nfrom openapi_first.client import OpenAPIClient\n\nspec = load_openapi(\"openapi.yaml\")\nclient = OpenAPIClient(spec)\n\n# List items\nresponse = client.list_items()\n\n# Get item by ID\nresponse = client.get_item(\n    path_params={\"item_id\": 1}\n)\n\n# Create item\nresponse = client.create_item(\n    body={\"name\": \"Orange\", \"price\": 0.8}\n)\n\n# Update item\nresponse = client.update_item(\n    path_params={\"item_id\": 1},\n    body={\"name\": \"Green Apple\", \"price\": 0.6},\n)\n\n# Delete item\nresponse = client.delete_item(\n    path_params={\"item_id\": 1}\n)\n</code></pre> <p>Client guarantees: - One callable per OpenAPI <code>operationId</code> - No hardcoded URLs or HTTP methods in user code - Request and response payloads conform to Pydantic models - Invalid or incomplete OpenAPI specs fail at client construction time</p>"},{"location":"openapi_first/templates/model_app/#openapi_first.templates.model_app--non-goals","title":"Non-Goals","text":"<p>This template is intentionally minimal and is NOT: - production-ready - persistent or concurrency-safe - a reference architecture for data storage</p> <p>It exists solely as a copyable example for learning, testing, and bootstrapping OpenAPI-first services.</p> <p>This package is not part of the <code>openapi_first</code> library API surface.</p>"},{"location":"openapi_first/templates/model_app/data/","title":"Data","text":""},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data","title":"openapi_first.templates.model_app.data","text":"<p>In-memory data store using Pydantic models.</p> <p>This module is NOT thread-safe and is intended for demos and scaffolds only. This module provides a minimal, process-local data store for the model-based CRUD example application. It stores and returns domain objects defined using Pydantic models and is intended solely for demonstration and scaffolding purposes.</p> <p>The implementation intentionally avoids: - persistence - concurrency guarantees - transactional semantics - validation beyond what Pydantic provides</p> <p>It is not part of the <code>openapi_first</code> library API surface.</p>"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.create_item","title":"create_item","text":"<pre><code>create_item(payload: ItemCreate) -&gt; Item\n</code></pre> <p>Create a new item in the data store.</p> <p>A new identifier is assigned automatically. No additional validation is performed beyond Pydantic model validation.</p>"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.create_item--parameters","title":"Parameters","text":"<p>payload : ItemCreate     Data required to create a new item.</p>"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.create_item--returns","title":"Returns","text":"<p>Item     The newly created item.</p>"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.delete_item","title":"delete_item","text":"<pre><code>delete_item(item_id: int) -&gt; None\n</code></pre> <p>Remove an item from the data store.</p>"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.delete_item--parameters","title":"Parameters","text":"<p>item_id : int     Identifier of the item to delete.</p>"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.delete_item--raises","title":"Raises","text":"<p>KeyError     If the item does not exist.</p>"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.get_item","title":"get_item","text":"<pre><code>get_item(item_id: int) -&gt; Item\n</code></pre> <p>Retrieve a single item by ID.</p>"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.get_item--parameters","title":"Parameters","text":"<p>item_id : int     Identifier of the item to retrieve.</p>"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.get_item--returns","title":"Returns","text":"<p>Item     The requested item.</p>"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.get_item--raises","title":"Raises","text":"<p>KeyError     If the item does not exist.</p>"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.list_items","title":"list_items","text":"<pre><code>list_items() -&gt; list[Item]\n</code></pre> <p>Return all items in the data store.</p>"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.list_items--returns","title":"Returns","text":"<p>list[Item]     A list of item domain objects.</p>"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.update_item","title":"update_item","text":"<pre><code>update_item(item_id: int, payload: ItemCreate) -&gt; Item\n</code></pre> <p>Replace an existing item in the data store.</p> <p>This function performs a full replacement of the stored item. Partial updates are not supported.</p>"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.update_item--parameters","title":"Parameters","text":"<p>item_id : int     Identifier of the item to update. payload : ItemCreate     New item data.</p>"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.update_item--returns","title":"Returns","text":"<p>Item     The updated item.</p>"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.update_item--raises","title":"Raises","text":"<p>KeyError     If the item does not exist.</p>"},{"location":"openapi_first/templates/model_app/main/","title":"Main","text":""},{"location":"openapi_first/templates/model_app/main/#openapi_first.templates.model_app.main","title":"openapi_first.templates.model_app.main","text":"<p>Application entry point for an OpenAPI-first model-based CRUD example service.</p> <p>This module constructs a FastAPI application exclusively from an OpenAPI specification and a handler namespace, without using decorator-driven routing.</p> <p>All HTTP routes, methods, request/response schemas, and operation bindings are defined in the OpenAPI document referenced by <code>openapi_path</code>. Python callables defined in the <code>routes</code> module are bound to OpenAPI operations strictly via <code>operationId</code>.</p> <p>This module contains no routing logic, persistence concerns, or framework configuration beyond application assembly.</p> <p>Design guarantees: - OpenAPI is the single source of truth - No undocumented routes can exist - Every OpenAPI operationId must resolve to exactly one handler - All contract violations fail at application startup</p> <p>This file is intended to be used as the ASGI entry point.</p> Example <p>uvicorn main:app</p>"},{"location":"openapi_first/templates/model_app/models/","title":"Models","text":""},{"location":"openapi_first/templates/model_app/models/#openapi_first.templates.model_app.models","title":"openapi_first.templates.model_app.models","text":"<p>Pydantic domain models for the CRUD example.</p> <p>This module defines Pydantic models that represent the domain entities used by the service. These models are referenced by the OpenAPI specification for request and response schemas.</p> <p>The models are declarative and framework-agnostic. They contain no persistence logic, validation beyond type constraints, or business behavior.</p> <p>This module is not part of the <code>openapi_first</code> library API surface. It exists solely to support the example application template.</p>"},{"location":"openapi_first/templates/model_app/models/#openapi_first.templates.model_app.models.Item","title":"Item","text":"<p>               Bases: <code>ItemBase</code></p> <p>Domain model for a persisted item.</p> <p>This model represents the full item state returned in responses, including the server-assigned identifier.</p>"},{"location":"openapi_first/templates/model_app/models/#openapi_first.templates.model_app.models.ItemBase","title":"ItemBase","text":"<p>               Bases: <code>BaseModel</code></p> <p>Base domain model for an item.</p> <p>Defines fields common to all item representations.</p>"},{"location":"openapi_first/templates/model_app/models/#openapi_first.templates.model_app.models.ItemCreate","title":"ItemCreate","text":"<p>               Bases: <code>ItemBase</code></p> <p>Domain model for item creation requests.</p> <p>This model is used for request bodies when creating new items. It intentionally excludes the <code>id</code> field, which is assigned by the service.</p>"},{"location":"openapi_first/templates/model_app/routes/","title":"Routes","text":""},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes","title":"openapi_first.templates.model_app.routes","text":"<p>CRUD route handlers bound via OpenAPI operationId.</p> <p>This module defines OpenAPI-bound operation handlers for a model-based CRUD service. Functions in this module are bound to HTTP routes exclusively via OpenAPI <code>operationId</code> values.</p> <p>Handlers explicitly control HTTP response status codes to ensure runtime behavior matches the OpenAPI contract. Domain models defined using Pydantic are used for request and response payloads.</p> <p>No routing decorators, path definitions, or implicit framework behavior appear in this module. All routing, HTTP methods, and schemas are defined in the OpenAPI specification.</p>"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.create_item","title":"create_item","text":"<pre><code>create_item(payload: ItemCreate, response: Response)\n</code></pre> <p>Create a new item.</p> <p>Implements the OpenAPI operation identified by <code>operationId: create_item</code>.</p>"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.create_item--parameters","title":"Parameters","text":"<p>payload : ItemCreate     Request body describing the item to create. response : fastapi.Response     Response object used to set the HTTP status code.</p>"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.create_item--returns","title":"Returns","text":"<p>Item     The newly created item.</p>"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.delete_item","title":"delete_item","text":"<pre><code>delete_item(item_id: int, response: Response)\n</code></pre> <p>Delete an existing item.</p> <p>Implements the OpenAPI operation identified by <code>operationId: delete_item</code>.</p>"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.delete_item--parameters","title":"Parameters","text":"<p>item_id : int     Identifier of the item to delete. response : fastapi.Response     Response object used to set the HTTP status code.</p>"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.delete_item--returns","title":"Returns","text":"<p>None     No content.</p>"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.delete_item--raises","title":"Raises","text":"<p>HTTPException     404 if the item does not exist.</p>"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.get_item","title":"get_item","text":"<pre><code>get_item(item_id: int)\n</code></pre> <p>Retrieve a single item by ID.</p> <p>Implements the OpenAPI operation identified by <code>operationId: get_item</code>.</p>"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.get_item--parameters","title":"Parameters","text":"<p>item_id : int     Identifier of the item to retrieve.</p>"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.get_item--returns","title":"Returns","text":"<p>Item     The requested item.</p>"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.get_item--raises","title":"Raises","text":"<p>HTTPException     404 if the item does not exist.</p>"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.list_items","title":"list_items","text":"<pre><code>list_items()\n</code></pre> <p>List all items.</p> <p>Implements the OpenAPI operation identified by <code>operationId: list_items</code>.</p>"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.list_items--returns","title":"Returns","text":"<p>list[Item]     A list of item domain objects.</p>"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.update_item","title":"update_item","text":"<pre><code>update_item(item_id: int, payload: ItemCreate)\n</code></pre> <p>Update an existing item.</p> <p>Implements the OpenAPI operation identified by <code>operationId: update_item</code>.</p>"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.update_item--parameters","title":"Parameters","text":"<p>item_id : int     Identifier of the item to update. payload : ItemCreate     New item data.</p>"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.update_item--returns","title":"Returns","text":"<p>Item     The updated item.</p>"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.update_item--raises","title":"Raises","text":"<p>HTTPException     404 if the item does not exist.</p>"},{"location":"openapi_first/templates/model_app/test_model_app/","title":"Test Model App","text":""},{"location":"openapi_first/templates/model_app/test_model_app/#openapi_first.templates.model_app.test_model_app","title":"openapi_first.templates.model_app.test_model_app","text":"<p>End-to-end tests for the OpenAPI-first model CRUD example app.</p> <p>These tests validate that all CRUD operations behave correctly against the in-memory mock data store using Pydantic models. - OpenAPI specification loading - OperationId-driven route binding on the server - OperationId-driven client invocation - Pydantic model-based request and response handling</p> <p>All CRUD operations are exercised against an in-memory mock data store backed by Pydantic domain models.</p> <p>The tests assume: - OpenAPI-first route binding - Pydantic model validation - In-memory storage (no persistence guarantees) - Deterministic behavior in a single process</p>"},{"location":"openapi_first/templates/model_app/test_model_app/#openapi_first.templates.model_app.test_model_app.test_create_item","title":"test_create_item","text":"<pre><code>test_create_item()\n</code></pre> <p>Creating a new item should return the created entity.</p>"},{"location":"openapi_first/templates/model_app/test_model_app/#openapi_first.templates.model_app.test_model_app.test_delete_item","title":"test_delete_item","text":"<pre><code>test_delete_item()\n</code></pre> <p>Deleting an item should remove it from the store.</p>"},{"location":"openapi_first/templates/model_app/test_model_app/#openapi_first.templates.model_app.test_model_app.test_get_item","title":"test_get_item","text":"<pre><code>test_get_item()\n</code></pre> <p>Existing item should be retrievable by ID.</p>"},{"location":"openapi_first/templates/model_app/test_model_app/#openapi_first.templates.model_app.test_model_app.test_list_items_initial","title":"test_list_items_initial","text":"<pre><code>test_list_items_initial()\n</code></pre> <p>Initial items should be present.</p>"},{"location":"openapi_first/templates/model_app/test_model_app/#openapi_first.templates.model_app.test_model_app.test_update_item","title":"test_update_item","text":"<pre><code>test_update_item()\n</code></pre> <p>Updating an item should replace its values.</p>"}]}