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

{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"openapi_first","text":""},{"location":"#openapi_first","title":"openapi_first","text":""},{"location":"#openapi_first--summary","title":"Summary","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 <code>operationId</code>.</p>"},{"location":"#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>"},{"location":"#openapi_first--quick-start","title":"Quick Start","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</code></pre> <p>OperationId-driven HTTP client:</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</code></pre>"},{"location":"#openapi_first--architecture","title":"Architecture","text":"<p>The library is structured around four core responsibilities:</p> <ul> <li><code>loader</code>: Load and validate OpenAPI 3.x specifications (JSON/YAML).</li> <li><code>binder</code>: Bind OpenAPI operations to FastAPI routes via <code>operationId</code>.</li> <li><code>app</code>: OpenAPI-first FastAPI application bootstrap.</li> <li><code>client</code>: OpenAPI-first HTTP client driven by the same specification.</li> <li><code>errors</code>: Explicit error hierarchy for contract violations.</li> </ul>"},{"location":"#openapi_first--public-api","title":"Public API","text":"<p>The supported public API consists of the following top-level modules:</p> <ul> <li><code>openapi_first.app</code></li> <li><code>openapi_first.binder</code></li> <li><code>openapi_first.loader</code></li> <li><code>openapi_first.client</code></li> <li><code>openapi_first.errors</code></li> </ul>"},{"location":"#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> </ul>"},{"location":"app/","title":"App","text":""},{"location":"app/#openapi_first.app","title":"openapi_first.app","text":""},{"location":"app/#openapi_first.app--summary","title":"Summary","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> Notes <p>Core Principles:</p> <pre><code>- The OpenAPI specification (JSON or YAML) defines the entire API surface.\n- Every `operationId` in the OpenAPI spec must have a corresponding\n  Python handler function.\n- Handlers are plain Python callables (no FastAPI decorators).\n- FastAPI route registration is derived exclusively from the spec.\n- FastAPI's autogenerated OpenAPI schema is fully overridden.\n</code></pre> <p>Responsibilities:</p> <pre><code>- Loads and validates an OpenAPI 3.x specification.\n- Dynamically binds HTTP routes to handler functions using `operationId`.\n- Registers routes with FastAPI at application startup.\n- Ensures runtime behavior matches the OpenAPI contract exactly.\n</code></pre> <p>Constraints:</p> <pre><code>- This module intentionally does NOT:\n    - Generate OpenAPI specs.\n    - Generate client code.\n    - Introduce a new framework or lifecycle.\n    - Alter FastAPI dependency injection semantics.\n</code></pre>"},{"location":"app/#openapi_first.app-classes","title":"Classes","text":""},{"location":"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> Notes <p>Responsibilities:</p> <pre><code>- `OpenAPIFirstApp` subclasses `FastAPI` and replaces manual route\n  registration with OpenAPI-driven binding.\n- All routes are derived from the provided OpenAPI specification,\n  and each `operationId` is mapped to a Python function in the\n  supplied routes module.\n</code></pre> <p>Guarantees:</p> <pre><code>- 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</code></pre> Example <pre><code>from openapi_first import OpenAPIFirstApp\nimport app.routes as routes\n\napp = OpenAPIFirstApp(\n    openapi_path=\"app/openapi.json\",\n    routes_module=routes,\n    title=\"Example Service\",\n)\n</code></pre> <p>Initialize the application.</p> <p>Parameters:</p> Name Type Description Default <code>openapi_path</code> <code>str</code> <p>Filesystem path to the OpenAPI 3.x specification file. This specification is treated as the authoritative API contract.</p> required <code>routes_module</code> <code>module</code> <p>Python module containing handler functions whose names correspond exactly to OpenAPI <code>operationId</code> values.</p> required <code>**fastapi_kwargs</code> <code>Any</code> <p>Additional keyword arguments passed directly to <code>fastapi.FastAPI</code> (e.g., title, version, middleware, lifespan handlers).</p> <code>{}</code> <p>Raises:</p> Type Description <code>OpenAPIFirstError</code> <p>If the OpenAPI specification is invalid, or if any declared <code>operationId</code> does not have a corresponding handler function.</p>"},{"location":"app/#openapi_first.app.OpenAPIFirstApp-functions","title":"Functions","text":""},{"location":"app/#openapi_first.app-functions","title":"Functions","text":""},{"location":"binder/","title":"Binder","text":""},{"location":"binder/#openapi_first.binder","title":"openapi_first.binder","text":""},{"location":"binder/#openapi_first.binder--summary","title":"Summary","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 <code>operationId</code>.</p> Notes <p>Core Responsibility:</p> <pre><code>- Read path + method definitions from an OpenAPI specification.\n- Resolve each `operationId` to a Python callable.\n- Register routes with FastAPI using `APIRoute`.\n- Fail fast when contract violations are detected.\n</code></pre> <p>Design Constraints:</p> <pre><code>- All routes MUST be declared in the OpenAPI specification.\n- All OpenAPI operations MUST define an `operationId`.\n- Every `operationId` MUST resolve to a handler function.\n- Handlers are plain Python callables (no decorators required).\n- No implicit route creation or inference is allowed.\n</code></pre> <p>Constraints:</p> <pre><code>- This module intentionally does NOT:\n    - Perform request or response validation.\n    - Generate Pydantic models.\n    - Modify FastAPI dependency injection.\n    - Interpret OpenAPI semantics beyond routing metadata.\n</code></pre>"},{"location":"binder/#openapi_first.binder-classes","title":"Classes","text":""},{"location":"binder/#openapi_first.binder-functions","title":"Functions","text":""},{"location":"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>Parameters:</p> Name Type Description Default <code>app</code> <code>FastAPI</code> <p>The FastAPI application instance to which routes will be added.</p> required <code>spec</code> <code>dict</code> <p>Parsed OpenAPI 3.x specification dictionary.</p> required <code>routes_module</code> <code>module</code> <p>Python module containing handler functions. Each handler's name MUST exactly match an OpenAPI <code>operationId</code>.</p> required <p>Raises:</p> Type Description <code>MissingOperationHandler</code> <p>If an <code>operationId</code> is missing from the spec or if no corresponding handler function exists in the routes module.</p> Notes <p>Responsibilities:</p> <pre><code>- Iterates through the OpenAPI specification paths and methods.\n- Resolves each `operationId` to a handler function, and registers\n  a corresponding `APIRoute` on the FastAPI application.\n</code></pre> <p>Guarantees:</p> <pre><code>- Route registration is deterministic and spec-driven. No route\n  decorators are required or supported. Handler resolution errors\n  surface at application startup.\n</code></pre>"},{"location":"cli/","title":"Cli","text":""},{"location":"cli/#openapi_first.cli","title":"openapi_first.cli","text":"<p>Command-line interface for FastAPI OpenAPI-first scaffolding utilities.</p>"},{"location":"cli/#openapi_first.cli--summary","title":"Summary","text":"<p>This CLI bootstraps OpenAPI-first FastAPI applications from versioned, bundled templates packaged with the library.</p>"},{"location":"cli/#openapi_first.cli-functions","title":"Functions","text":""},{"location":"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> <p>Returns:</p> Type Description <code>list[str]</code> <p>list[str]: Sorted list of template names found in the internal templates directory.</p>"},{"location":"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> <p>Parameters:</p> Name Type Description Default <code>template</code> <code>str</code> <p>Name of the template to copy.</p> required <code>target_dir</code> <code>Path</code> <p>Filesystem path where the template should be copied.</p> required <p>Raises:</p> Type Description <code>FileNotFoundError</code> <p>If the requested template does not exist.</p>"},{"location":"client/","title":"Client","text":""},{"location":"client/#openapi_first.client","title":"openapi_first.client","text":""},{"location":"client/#openapi_first.client--summary","title":"Summary","text":"<p>OpenAPI-first HTTP client for contract-driven services.</p> <p>This module provides <code>OpenAPIClient</code>, a thin, strict HTTP client that derives all callable operations directly from an OpenAPI 3.x specification.</p> <p>It is the client counterpart to <code>OpenAPIFirstApp</code>.</p> Notes <p>Core Principles:</p> <pre><code>- The OpenAPI specification is the single source of truth\n- Each operationId becomes a callable Python method\n- No implicit schema mutation or inference\n- No code generation step\n- Minimal abstraction over httpx\n</code></pre> <p>Responsibilities:</p> <pre><code>- Parses an OpenAPI 3.x specification\n- Dynamically creates one callable per operationId\n- Enforces presence of servers, paths, and operationId\n- Formats path parameters safely\n- Handles JSON request bodies explicitly\n- Returns raw `httpx.Response` objects\n</code></pre> <p>Constraints:</p> <pre><code>- This module intentionally does NOT: Generate client code, validate request/response schemas, deserialize responses, retry requests, implement authentication helpers, or assume non-2xx responses are failures.\n</code></pre>"},{"location":"client/#openapi_first.client-classes","title":"Classes","text":""},{"location":"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 (<code>httpx</code>-based).</p> Notes <p>Responsibilities:</p> <pre><code>- This client derives all callable methods directly from an\n  OpenAPI 3.x specification. Each `operationId` becomes a method\n  on the client instance.\n</code></pre> <p>Guarantees:</p> <pre><code>- One callable per `operationId`.\n- Explicit parameters (path, query, headers, body).\n- No implicit schema inference or mutation.\n- Returns raw `httpx.Response` objects.\n- No response validation or deserialization.\n</code></pre> Example <pre><code>from openapi_first import loader, client\n\nspec = loader.load_openapi(\"openapi.yaml\")\n\napi = client.OpenAPIClient(\n    spec=spec,\n    base_url=\"http://localhost:8000\",\n)\n\n# Call operationId: getUser\nresponse = api.getUser(\n    path_params={\"user_id\": 123}\n)\n\nprint(response.status_code)\nprint(response.json())\n</code></pre> <p>Initialize the OpenAPI client.</p> <p>Parameters:</p> Name Type Description Default <code>spec</code> <code>dict[str, Any]</code> <p>Parsed OpenAPI 3.x specification.</p> required <code>base_url</code> <code>str</code> <p>Base URL of the target service. If omitted, the first entry in the OpenAPI <code>servers</code> list is used.</p> <code>None</code> <code>client</code> <code>Client</code> <p>Optional preconfigured httpx client instance.</p> <code>None</code> <p>Raises:</p> Type Description <code>OpenAPIClientError</code> <p>If no servers are defined, spec has no paths, operationIds are missing/duplicate, or required parameters are missing.</p>"},{"location":"client/#openapi_first.client.OpenAPIClient-functions","title":"Functions","text":""},{"location":"client/#openapi_first.client.OpenAPIClientError","title":"OpenAPIClientError","text":"<p>               Bases: <code>OpenAPIFirstError</code></p> <p>Raised when an OpenAPI client operation fails.</p>"},{"location":"errors/","title":"Errors","text":""},{"location":"errors/#openapi_first.errors","title":"openapi_first.errors","text":""},{"location":"errors/#openapi_first.errors--summary","title":"Summary","text":"<p>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> Notes <p>Design Principles:</p> <pre><code>- Errors represent programmer mistakes, not runtime conditions.\n- All errors are raised during application startup.\n- Messages are actionable and suitable for CI/CD output.\n- Exceptions are explicit rather than reused from generic built-ins.\n</code></pre> <p>These errors should normally cause immediate application failure.</p>"},{"location":"errors/#openapi_first.errors-classes","title":"Classes","text":""},{"location":"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> Notes <p>Scenarios:</p> <pre><code>- An OpenAPI operation does not define an `operationId`.\n- An `operationId` is defined but no matching function exists in\n  the provided routes module.\n</code></pre> <p>Guarantees:</p> <pre><code>- This represents a violation of the OpenAPI-first contract and\n  indicates that the specification and implementation are out of\n  sync.\n</code></pre> <p>Initialize the error.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>The HTTP path declared in the OpenAPI specification.</p> required <code>method</code> <code>str</code> <p>The HTTP method (as declared in the OpenAPI spec).</p> required <code>operation_id</code> <code>str</code> <p>The operationId declared in the OpenAPI spec, if present.</p> <code>None</code>"},{"location":"errors/#openapi_first.errors.MissingOperationHandler-functions","title":"Functions","text":""},{"location":"errors/#openapi_first.errors.OpenAPIFirstError","title":"OpenAPIFirstError","text":"<p>               Bases: <code>Exception</code></p> <p>Base exception for all OpenAPI-first enforcement errors.</p> Notes <p>Responsibilities:</p> <pre><code>- This exception exists to allow callers, test suites, and CI\n  pipelines to catch and distinguish OpenAPI contract violations\n  from unrelated runtime errors.\n- All exceptions raised by the OpenAPI-first core should inherit\n  from this type.\n</code></pre>"},{"location":"loader/","title":"Loader","text":""},{"location":"loader/#openapi_first.loader","title":"openapi_first.loader","text":""},{"location":"loader/#openapi_first.loader--summary","title":"Summary","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> Notes <p>Design Principles:</p> <pre><code>- OpenAPI is treated as an authoritative contract.\n- Invalid specifications fail fast at application startup.\n- Supported formats are JSON and YAML.\n- Validation errors are surfaced clearly and early.\n</code></pre> <p>Constraints:</p> <pre><code>- This module intentionally does NOT:\n    - Modify the OpenAPI document.\n    - Infer missing fields.\n    - Generate models or code.\n    - Perform request/response validation at runtime.\n</code></pre>"},{"location":"loader/#openapi_first.loader-classes","title":"Classes","text":""},{"location":"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> Notes <p>Guarantees:</p> <pre><code>- This error indicates that the OpenAPI document is unreadable,\n  malformed, or violates the OpenAPI 3.x specification.\n</code></pre>"},{"location":"loader/#openapi_first.loader-functions","title":"Functions","text":""},{"location":"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>Parameters:</p> Name Type Description Default <code>path</code> <code>str | Path</code> <p>Filesystem path to an OpenAPI specification file. Supported extensions: <code>.json</code>, <code>.yaml</code>, <code>.yml</code>.</p> required <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>dict[str, Any]: Parsed and validated OpenAPI specification.</p> <p>Raises:</p> Type Description <code>OpenAPISpecLoadError</code> <p>If the file does not exist, cannot be parsed, or fails OpenAPI schema validation.</p> Notes <p>Guarantees:</p> <pre><code>- The specification is parsed based on file extension and validated\n  using a strict OpenAPI schema validator.\n- Any error results in an immediate exception, preventing\n  application startup.\n</code></pre>"}]}