{"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":"

FastAPI OpenAPI First \u2014 strict OpenAPI-first application bootstrap for FastAPI.

FastAPI OpenAPI First is a contract-first infrastructure library that enforces OpenAPI as the single source of truth for FastAPI services.

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.

"},{"location":"#openapi_first--installation","title":"Installation","text":"

Install using pip:

pip install openapi-first\n

Or with Poetry:

poetry add openapi-first\n
"},{"location":"#openapi_first--quick-start","title":"Quick Start","text":"

Minimal OpenAPI-first FastAPI application:

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

OperationId-driven HTTP client:

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
"},{"location":"#openapi_first--architecture","title":"Architecture","text":"

The library is structured around four core responsibilities:

"},{"location":"#openapi_first--public-api","title":"Public API","text":"

The supported public API consists of the following top-level modules:

"},{"location":"#openapi_first--design-guarantees","title":"Design Guarantees","text":""},{"location":"app/","title":"App","text":""},{"location":"app/#openapi_first.app","title":"openapi_first.app","text":""},{"location":"app/#openapi_first.app--summary","title":"Summary","text":"

OpenAPI-first application bootstrap for FastAPI.

This module provides OpenAPIFirstApp, a thin but strict abstraction that enforces OpenAPI as the single source of truth for a FastAPI service.

Notes

Core Principles:

- 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

Responsibilities:

- 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

Constraints:

- 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
"},{"location":"app/#openapi_first.app-classes","title":"Classes","text":""},{"location":"app/#openapi_first.app.OpenAPIFirstApp","title":"OpenAPIFirstApp","text":"
OpenAPIFirstApp(*, openapi_path: str, routes_module: Any, **fastapi_kwargs: Any)\n

Bases: FastAPI

FastAPI application enforcing OpenAPI-first design.

Notes

Responsibilities:

- `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

Guarantees:

- 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
Example 
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

Initialize the application.

Parameters:

Name Type Description Default openapi_path str

Filesystem path to the OpenAPI 3.x specification file. This specification is treated as the authoritative API contract.

required routes_module module

Python module containing handler functions whose names correspond exactly to OpenAPI operationId values.

required **fastapi_kwargs Any

Additional keyword arguments passed directly to fastapi.FastAPI (e.g., title, version, middleware, lifespan handlers).

{}

Raises:

Type Description OpenAPIFirstError

If the OpenAPI specification is invalid, or if any declared operationId does not have a corresponding handler function.

"},{"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":"

OpenAPI-driven route binding for FastAPI.

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.

Notes

Core Responsibility:

- 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

Design Constraints:

- 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

Constraints:

- 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
"},{"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":"
bind_routes(app: FastAPI, spec: Dict[str, Any], routes_module: Any) -> None\n

Bind OpenAPI operations to FastAPI routes.

Parameters:

Name Type Description Default app FastAPI

The FastAPI application instance to which routes will be added.

required spec dict

Parsed OpenAPI 3.x specification dictionary.

required routes_module module

Python module containing handler functions. Each handler's name MUST exactly match an OpenAPI operationId.

required

Raises:

Type Description MissingOperationHandler

If an operationId is missing from the spec or if no corresponding handler function exists in the routes module.

Notes

Responsibilities:

- 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

Guarantees:

- Route registration is deterministic and spec-driven. No route\n  decorators are required or supported. Handler resolution errors\n  surface at application startup.\n
"},{"location":"cli/","title":"Cli","text":""},{"location":"cli/#openapi_first.cli","title":"openapi_first.cli","text":"

Command-line interface for FastAPI OpenAPI-first scaffolding utilities.

"},{"location":"cli/#openapi_first.cli--summary","title":"Summary","text":"

This CLI bootstraps OpenAPI-first FastAPI applications from versioned, bundled templates packaged with the library.

"},{"location":"cli/#openapi_first.cli-functions","title":"Functions","text":""},{"location":"cli/#openapi_first.cli.available_templates","title":"available_templates","text":"
available_templates() -> list[str]\n

Return a list of available application templates.

Returns:

Type Description list[str]

list[str]: Sorted list of template names found in the internal templates directory.

"},{"location":"cli/#openapi_first.cli.copy_template","title":"copy_template","text":"
copy_template(template: str, target_dir: Path) -> None\n

Copy a bundled OpenAPI-first application template into a directory.

Parameters:

Name Type Description Default template str

Name of the template to copy.

required target_dir Path

Filesystem path where the template should be copied.

required

Raises:

Type Description FileNotFoundError

If the requested template does not exist.

"},{"location":"client/","title":"Client","text":""},{"location":"client/#openapi_first.client","title":"openapi_first.client","text":""},{"location":"client/#openapi_first.client--summary","title":"Summary","text":"

OpenAPI-first HTTP client for contract-driven services.

This module provides OpenAPIClient, a thin, strict HTTP client that derives all callable operations directly from an OpenAPI 3.x specification.

It is the client counterpart to OpenAPIFirstApp.

Notes

Core Principles:

- 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

Responsibilities:

- 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

Constraints:

- 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
"},{"location":"client/#openapi_first.client-classes","title":"Classes","text":""},{"location":"client/#openapi_first.client.OpenAPIClient","title":"OpenAPIClient","text":"
OpenAPIClient(spec: Dict[str, Any], base_url: Optional[str] = None, client: Optional[httpx.Client] = None)\n

OpenAPI-first HTTP client (httpx-based).

Notes

Responsibilities:

- 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

Guarantees:

- 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
Example 
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

Initialize the OpenAPI client.

Parameters:

Name Type Description Default spec dict[str, Any]

Parsed OpenAPI 3.x specification.

required base_url str

Base URL of the target service. If omitted, the first entry in the OpenAPI servers list is used.

None client Client

Optional preconfigured httpx client instance.

None

Raises:

Type Description OpenAPIClientError

If no servers are defined, spec has no paths, operationIds are missing/duplicate, or required parameters are missing.

"},{"location":"client/#openapi_first.client.OpenAPIClient-functions","title":"Functions","text":""},{"location":"client/#openapi_first.client.OpenAPIClientError","title":"OpenAPIClientError","text":"

Bases: OpenAPIFirstError

Raised when an OpenAPI client operation fails.

"},{"location":"errors/","title":"Errors","text":""},{"location":"errors/#openapi_first.errors","title":"openapi_first.errors","text":""},{"location":"errors/#openapi_first.errors--summary","title":"Summary","text":"

Exceptions for OpenAPI-first FastAPI applications.

This module defines a small hierarchy of explicit, intention-revealing exceptions used to signal contract violations between an OpenAPI specification and its Python implementation.

Notes

Design Principles:

- 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

These errors should normally cause immediate application failure.

"},{"location":"errors/#openapi_first.errors-classes","title":"Classes","text":""},{"location":"errors/#openapi_first.errors.MissingOperationHandler","title":"MissingOperationHandler","text":"
MissingOperationHandler(*, path: str, method: str, operation_id: Optional[str] = None)\n

Bases: OpenAPIFirstError

Raised when an OpenAPI operation cannot be resolved to a handler.

Notes

Scenarios:

- 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

Guarantees:

- This represents a violation of the OpenAPI-first contract and\n  indicates that the specification and implementation are out of\n  sync.\n

Initialize the error.

Parameters:

Name Type Description Default path str

The HTTP path declared in the OpenAPI specification.

required method str

The HTTP method (as declared in the OpenAPI spec).

required operation_id str

The operationId declared in the OpenAPI spec, if present.

None"},{"location":"errors/#openapi_first.errors.MissingOperationHandler-functions","title":"Functions","text":""},{"location":"errors/#openapi_first.errors.OpenAPIFirstError","title":"OpenAPIFirstError","text":"

Bases: Exception

Base exception for all OpenAPI-first enforcement errors.

Notes

Responsibilities:

- 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
"},{"location":"loader/","title":"Loader","text":""},{"location":"loader/#openapi_first.loader","title":"openapi_first.loader","text":""},{"location":"loader/#openapi_first.loader--summary","title":"Summary","text":"

OpenAPI specification loading and validation utilities.

This module is responsible for loading an OpenAPI 3.x specification from disk and validating it before it is used by the application.

It enforces the principle that an invalid or malformed OpenAPI document must never reach the routing or runtime layers.

Notes

Design Principles:

- 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

Constraints:

- 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
"},{"location":"loader/#openapi_first.loader-classes","title":"Classes","text":""},{"location":"loader/#openapi_first.loader.OpenAPISpecLoadError","title":"OpenAPISpecLoadError","text":"

Bases: OpenAPIFirstError

Raised when an OpenAPI specification cannot be loaded or validated.

Notes

Guarantees:

- This error indicates that the OpenAPI document is unreadable,\n  malformed, or violates the OpenAPI 3.x specification.\n
"},{"location":"loader/#openapi_first.loader-functions","title":"Functions","text":""},{"location":"loader/#openapi_first.loader.load_openapi","title":"load_openapi","text":"
load_openapi(path: Union[str, Path]) -> Dict[str, Any]\n

Load and validate an OpenAPI 3.x specification from disk.

Parameters:

Name Type Description Default path str | Path

Filesystem path to an OpenAPI specification file. Supported extensions: .json, .yaml, .yml.

required

Returns:

Type Description Dict[str, Any]

dict[str, Any]: Parsed and validated OpenAPI specification.

Raises:

Type Description OpenAPISpecLoadError

If the file does not exist, cannot be parsed, or fails OpenAPI schema validation.

Notes

Guarantees:

- 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
"}]}