{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"openapi_first/","title":"Openapi First","text":""},{"location":"openapi_first/#openapi_first","title":"openapi_first","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.

The package is intentionally minimal and layered. Each module has a single responsibility and exposes explicit contracts rather than convenience facades.

"},{"location":"openapi_first/#openapi_first--architecture-overview","title":"Architecture Overview","text":"

The library is structured around four core responsibilities:

The package root acts as a namespace, not a facade. Consumers are expected to import functionality explicitly from the appropriate module.

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

Install using pip:

pip install openapi-first\n

Or with Poetry:

poetry add openapi-first\n

Runtime dependencies are intentionally minimal: - fastapi (server-side) - httpx (client-side) - openapi-spec-validator - pyyaml (optional, for YAML specs)

The ASGI server (e.g., uvicorn) is an application-level dependency and is not bundled with this library.

"},{"location":"openapi_first/#openapi_first--command-line-interface-scaffolding-templates","title":"Command-Line Interface (Scaffolding, Templates)","text":"

FastAPI OpenAPI First ships with a small CLI for bootstrapping OpenAPI-first FastAPI applications from bundled templates.

List available application templates:

openapi-first --list\n

Create a new application using the default template:

openapi-first\n

Create a new application using a specific template:

openapi-first health_app\n

Create a new application in a custom directory:

openapi-first health_app my-service\n

The CLI copies template files verbatim into the target directory. No code is generated or modified beyond the copied scaffold.

"},{"location":"openapi_first/#openapi_first--server-side-usage-openapi-fastapi","title":"Server-Side Usage (OpenAPI \u2192 FastAPI)","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\n# Run with:\n# uvicorn my_service.main:api\n

Handler definitions (no decorators):

def get_health():\n    return {\"status\": \"ok\"}\n

OpenAPI snippet:

paths:\n  /health:\n    get:\n      operationId: get_health\n      responses:\n        \"200\":\n          description: OK\n

The binder guarantees: - Every OpenAPI operationId has exactly one handler - No undocumented routes exist - All mismatches fail at application startup

"},{"location":"openapi_first/#openapi_first--client-side-usage-openapi-http-client","title":"Client-Side Usage (OpenAPI \u2192 HTTP Client)","text":"

The same OpenAPI specification can be used to construct a strict, operationId-driven HTTP client.

Client construction:

from openapi_first.loader import load_openapi\nfrom openapi_first.client import OpenAPIClient\n\nspec = load_openapi(\"openapi.yaml\")\n\nclient = OpenAPIClient(spec)\n

Calling operations (operationId is the API):

response = client.get_health()\nassert response.status_code == 200\nassert response.json() == {\"status\": \"ok\"}\n

Path parameters must match the OpenAPI specification exactly:

response = client.get_item(\n    path_params={\"item_id\": 1}\n)\n

Request bodies are passed explicitly:

response = client.create_item(\n    body={\"name\": \"Orange\", \"price\": 0.8}\n)\n

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

The client is transport-level only and returns httpx.Response objects directly. Response interpretation and validation are left to the consumer or higher-level layers.

"},{"location":"openapi_first/#openapi_first--extensibility-model","title":"Extensibility Model","text":"

FastAPI OpenAPI First is designed to be extended via explicit contracts:

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.

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

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

Classes and functions should be imported explicitly from these modules. No individual symbols are re-exported at the package root.

"},{"location":"openapi_first/#openapi_first--design-guarantees","title":"Design Guarantees","text":"

FastAPI OpenAPI First favors correctness, explicitness, and contract enforcement over convenience shortcuts.

"},{"location":"openapi_first/#openapi_first--core-philosophy","title":"Core Philosophy","text":"

FastAPI OpenAPI First operates on the Contract-as-Code principle:

  1. Spec-Driven Routing: The OpenAPI document is the router. Code only exists to fulfill established contracts.
  2. Startup Fail-Fast: Binding mismatches (missing handlers or extra operations) are detected during app initialization, not at runtime.
  3. Decoupled Symmetry: The same specification drives both the FastAPI server and the httpx-based client, ensuring type-safe communication.
"},{"location":"openapi_first/#openapi_first--documentation-design","title":"Documentation Design","text":"

Follow these \"AI-Native\" docstring principles to maximize developer and agent productivity:

"},{"location":"openapi_first/#openapi_first--for-humans","title":"For Humans","text":""},{"location":"openapi_first/#openapi_first--for-llms","title":"For LLMs","text":""},{"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":"

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.

"},{"location":"openapi_first/app/#openapi_first.app--core-principles","title":"Core principles","text":""},{"location":"openapi_first/app/#openapi_first.app--what-this-module-does","title":"What this module does","text":""},{"location":"openapi_first/app/#openapi_first.app--what-this-module-does-not-do","title":"What this module does NOT do","text":""},{"location":"openapi_first/app/#openapi_first.app--intended-usage","title":"Intended usage","text":"

This module is intended for teams that want:

"},{"location":"openapi_first/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.

OpenAPIFirstApp 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.

"},{"location":"openapi_first/app/#openapi_first.app.OpenAPIFirstApp--parameters","title":"Parameters","text":"

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

module

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

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

"},{"location":"openapi_first/app/#openapi_first.app.OpenAPIFirstApp--raises","title":"Raises","text":"

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

"},{"location":"openapi_first/app/#openapi_first.app.OpenAPIFirstApp--behavior-guarantees","title":"Behavior guarantees","text":""},{"location":"openapi_first/app/#openapi_first.app.OpenAPIFirstApp--example","title":"Example","text":"

from openapi_first import OpenAPIFirstApp import app.routes as routes

app = OpenAPIFirstApp( ... openapi_path=\"app/openapi.json\", ... routes_module=routes, ... title=\"Example Service\" ... )

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

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.

"},{"location":"openapi_first/binder/#openapi_first.binder--core-responsibility","title":"Core responsibility","text":""},{"location":"openapi_first/binder/#openapi_first.binder--design-constraints","title":"Design constraints","text":""},{"location":"openapi_first/binder/#openapi_first.binder--this-module-intentionally-does-not","title":"This module intentionally does NOT:","text":"

Those concerns belong to other layers or tooling.

"},{"location":"openapi_first/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.

Iterates through the OpenAPI specification paths and methods, resolves each operationId to a handler function, and registers a corresponding APIRoute on the FastAPI application.

"},{"location":"openapi_first/binder/#openapi_first.binder.bind_routes--parameters","title":"Parameters","text":"

app : fastapi.FastAPI The FastAPI application instance to which routes will be added.

dict

Parsed OpenAPI 3.x specification dictionary.

module

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

"},{"location":"openapi_first/binder/#openapi_first.binder.bind_routes--raises","title":"Raises","text":"

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

"},{"location":"openapi_first/binder/#openapi_first.binder.bind_routes--behavior-guarantees","title":"Behavior guarantees","text":""},{"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":"

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

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

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

Return a list of available application templates.

"},{"location":"openapi_first/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.

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

OpenAPI-first HTTP client (httpx-based).

"},{"location":"openapi_first/client/#openapi_first.client.OpenAPIClientError","title":"OpenAPIClientError","text":"

Bases: OpenAPIFirstError

Raised when an OpenAPI client operation fails.

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

Custom 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.

"},{"location":"openapi_first/errors/#openapi_first.errors--design-principles","title":"Design principles","text":"

These errors should normally cause immediate application failure.

"},{"location":"openapi_first/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.

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.

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

"},{"location":"openapi_first/errors/#openapi_first.errors.MissingOperationHandler--parameters","title":"Parameters","text":"

path : str The HTTP path declared in the OpenAPI specification.

str

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

str, optional

The operationId declared in the OpenAPI spec, if present.

"},{"location":"openapi_first/errors/#openapi_first.errors.OpenAPIFirstError","title":"OpenAPIFirstError","text":"

Bases: Exception

Base exception for all OpenAPI-first enforcement errors.

This exception exists to allow callers, test suites, and CI pipelines to catch and distinguish OpenAPI contract violations from unrelated runtime errors.

All exceptions raised by the OpenAPI-first core should inherit from this type.

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

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.

"},{"location":"openapi_first/loader/#openapi_first.loader--design-principles","title":"Design principles","text":""},{"location":"openapi_first/loader/#openapi_first.loader--this-module-intentionally-does-not","title":"This module intentionally does NOT:","text":""},{"location":"openapi_first/loader/#openapi_first.loader.OpenAPISpecLoadError","title":"OpenAPISpecLoadError","text":"

Bases: OpenAPIFirstError

Raised when an OpenAPI specification cannot be loaded or validated.

This error indicates that the OpenAPI document is unreadable, malformed, or violates the OpenAPI 3.x specification.

"},{"location":"openapi_first/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.

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.

"},{"location":"openapi_first/loader/#openapi_first.loader.load_openapi--parameters","title":"Parameters","text":"

path : str or pathlib.Path Filesystem path to an OpenAPI specification file. Supported extensions: - .json - .yaml - .yml

"},{"location":"openapi_first/loader/#openapi_first.loader.load_openapi--returns","title":"Returns","text":"

dict Parsed and validated OpenAPI specification.

"},{"location":"openapi_first/loader/#openapi_first.loader.load_openapi--raises","title":"Raises","text":"

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

"},{"location":"openapi_first/templates/","title":"Templates","text":""},{"location":"openapi_first/templates/#openapi_first.templates","title":"openapi_first.templates","text":"

Application templates for FastAPI OpenAPI First.

This package contains example and scaffolding templates intended to be copied into user projects via the openapi-first CLI.

Templates in this package are: - Reference implementations of OpenAPI-first services - Not part of the openapi_first public or internal API - Not intended to be imported as runtime dependencies

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

No code in this package should be imported by library consumers.

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

OpenAPI-first CRUD application template.

This package contains a complete, minimal example of an OpenAPI-first CRUD service built using the openapi_first library.

The application is assembled exclusively from: - an OpenAPI specification (openapi.yaml) - a handler namespace implementing CRUD operations (routes) - an in-memory mock data store (data)

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.

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

"},{"location":"openapi_first/templates/crud_app/#openapi_first.templates.crud_app--scaffolding-via-cli","title":"Scaffolding via CLI","text":"

Create a new CRUD example service using the bundled template:

openapi-first crud_app\n

Create the service in a custom directory:

openapi-first crud_app my-crud-service\n

List all available application templates:

openapi-first --list\n

The CLI copies template files verbatim into the target directory. No code is generated or modified beyond the copied scaffold.

"},{"location":"openapi_first/templates/crud_app/#openapi_first.templates.crud_app--client-usage-example","title":"Client Usage Example","text":"

The same OpenAPI specification used by the server can be used to construct a strict, operationId-driven HTTP client.

Example client calls for CRUD operations:

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

Client guarantees: - One callable per OpenAPI operationId - 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

"},{"location":"openapi_first/templates/crud_app/#openapi_first.templates.crud_app--non-goals","title":"Non-Goals","text":"

This template is intentionally minimal and is NOT: - production-ready - persistent or concurrency-safe - a reference architecture for data storage

It exists solely as a copyable example for learning, testing, and bootstrapping OpenAPI-first services.

This package is not part of the openapi_first library API surface.

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

In-memory mock data store for CRUD example.

This module intentionally avoids persistence and concurrency guarantees. It is suitable for demos, tests, and scaffolding only.

It intentionally avoids - persistence - concurrency guarantees - validation - error handling

The implementation is suitable for: - demonstrations - tests - scaffolding and example services

It is explicitly NOT suitable for production use.

This module is not part of the openapi_first library API surface.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.create_item","title":"create_item","text":"
create_item(payload: dict)\n

Create a new item in the data store.

A new integer ID is assigned automatically. No validation is performed on the provided payload.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.create_item--parameters","title":"Parameters","text":"

payload : dict Item attributes excluding the id field.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.create_item--returns","title":"Returns","text":"

dict The newly created item, including its assigned ID.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.delete_item","title":"delete_item","text":"
delete_item(item_id: int)\n

Remove an item from the data store.

This function assumes the item exists and will raise KeyError if the ID is not present.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.delete_item--parameters","title":"Parameters","text":"

item_id : int Identifier of the item to delete.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.get_item","title":"get_item","text":"
get_item(item_id: int)\n

Retrieve a single item by ID.

This function assumes the item exists and will raise KeyError if the ID is not present in the store.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.get_item--parameters","title":"Parameters","text":"

item_id : int Identifier of the item to retrieve.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.get_item--returns","title":"Returns","text":"

dict The stored item representation.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.list_items","title":"list_items","text":"
list_items()\n

Return all items in the data store.

This function performs no filtering, pagination, or sorting. The returned collection reflects the current in-memory state.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.list_items--returns","title":"Returns","text":"

list[dict] A list of item representations.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.update_item","title":"update_item","text":"
update_item(item_id: int, payload: dict)\n

Replace an existing item in the data store.

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.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.update_item--parameters","title":"Parameters","text":"

item_id : int Identifier of the item to update. payload : dict Item attributes excluding the id field.

"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.update_item--returns","title":"Returns","text":"

dict The updated item representation.

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

Application entry point for an OpenAPI-first CRUD example service.

This module constructs a FastAPI application exclusively from an OpenAPI specification and a handler namespace, without using decorator-driven routing.

All HTTP routes, methods, request/response schemas, and operation bindings are defined in the OpenAPI document referenced by openapi_path. Python callables defined in the routes module are bound to OpenAPI operations strictly via operationId.

This module contains no routing logic, persistence concerns, or framework configuration beyond application assembly.

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

This file is intended to be used as the ASGI entry point.

Example

uvicorn main:app

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

CRUD route handlers bound via OpenAPI operationId.

These handlers explicitly control HTTP status codes to ensure runtime behavior matches the OpenAPI contract.

This module defines OpenAPI-bound operation handlers for a simple CRUD service. Functions in this module are bound to HTTP routes exclusively via OpenAPI operationId values.

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.

No routing decorators or path definitions appear in this module. All routing, HTTP methods, and schemas are defined in the OpenAPI specification.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.create_item","title":"create_item","text":"
create_item(payload: dict, response: Response)\n

Create a new item.

Implements the OpenAPI operation identified by operationId: create_item.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.create_item--parameters","title":"Parameters","text":"

payload : dict Item attributes excluding the id field. response : fastapi.Response Response object used to set the HTTP status code.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.create_item--returns","title":"Returns","text":"

dict The newly created item.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.delete_item","title":"delete_item","text":"
delete_item(item_id: int, response: Response)\n

Delete an existing item.

Implements the OpenAPI operation identified by operationId: delete_item.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.delete_item--parameters","title":"Parameters","text":"

item_id : int Identifier of the item to delete. response : fastapi.Response Response object used to set the HTTP status code.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.delete_item--returns","title":"Returns","text":"

None No content.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.delete_item--raises","title":"Raises","text":"

HTTPException 404 if the item does not exist.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.get_item","title":"get_item","text":"
get_item(item_id: int)\n

Retrieve a single item by ID.

Implements the OpenAPI operation identified by operationId: get_item.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.get_item--parameters","title":"Parameters","text":"

item_id : int Identifier of the item to retrieve.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.get_item--returns","title":"Returns","text":"

dict The requested item.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.get_item--raises","title":"Raises","text":"

HTTPException 404 if the item does not exist.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.list_items","title":"list_items","text":"
list_items()\n

List all items.

Implements the OpenAPI operation identified by operationId: list_items.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.list_items--returns","title":"Returns","text":"

list[dict] A list of item representations.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.update_item","title":"update_item","text":"
update_item(item_id: int, payload: dict)\n

Update an existing item.

Implements the OpenAPI operation identified by operationId: update_item.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.update_item--parameters","title":"Parameters","text":"

item_id : int Identifier of the item to update. payload : dict Item attributes excluding the id field.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.update_item--returns","title":"Returns","text":"

dict The updated item.

"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.update_item--raises","title":"Raises","text":"

HTTPException 404 if the item does not exist.

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

End-to-end tests for the OpenAPI-first CRUD example app.

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

The tests exercise all CRUD operations against an in-memory mock data store and assume deterministic behavior within a single process.

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

"},{"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":"
test_create_item()\n

Creating a new item should return the created entity.

"},{"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":"
test_delete_item()\n

Deleting an item should remove it from the store.

"},{"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":"
test_get_item()\n

Existing item should be retrievable by ID.

"},{"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":"
test_list_items_initial()\n

Initial items should be present.

"},{"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":"
test_update_item()\n

Updating an item should replace its values.

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

OpenAPI-first FastAPI application template.

This package contains a minimal, fully working example of an OpenAPI-first FastAPI service built using the openapi_first library.

The application is assembled exclusively from: - an OpenAPI specification (openapi.yaml) - a handler namespace (routes)

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.

This package is intended to be copied as a starting point for new services via the openapi-first CLI. It is not part of the openapi_first library API surface.

"},{"location":"openapi_first/templates/health_app/#openapi_first.templates.health_app--scaffolding-via-cli","title":"Scaffolding via CLI","text":"

Create a new OpenAPI-first health check service using the bundled template:

openapi-first health_app\n

Create the service in a custom directory:

openapi-first health_app my-health-service\n

List all available application templates:

openapi-first --list\n

The CLI copies template files verbatim into the target directory. No code is generated or modified beyond the copied scaffold.

"},{"location":"openapi_first/templates/health_app/#openapi_first.templates.health_app--client-usage-example","title":"Client Usage Example","text":"

The same OpenAPI specification used by the server can be used to construct a strict, operationId-driven HTTP client.

Example client call for the get_health operation:

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

Client guarantees: - One callable per OpenAPI operationId - 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

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

Application entry point for an OpenAPI-first FastAPI service.

This module constructs a FastAPI application exclusively from an OpenAPI specification and a handler namespace, without using decorator-driven routing.

All HTTP routes, methods, and operation bindings are defined in the OpenAPI document referenced by openapi_path. Python callables defined in the routes module are bound to OpenAPI operations strictly via operationId.

This module contains no routing logic, request handling, or framework configuration beyond application assembly.

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

This file is intended to be used as the ASGI entry point.

Example

uvicorn main:app

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

OpenAPI operation handlers.

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 operationId values.

No routing decorators, HTTP metadata, or framework-specific logic should appear here. All request/response semantics are defined in the OpenAPI specification.

This module serves solely as an operationId namespace.

"},{"location":"openapi_first/templates/health_app/routes/#openapi_first.templates.health_app.routes.get_health","title":"get_health","text":"
get_health()\n

Health check operation handler.

This function implements the OpenAPI operation identified by operationId: get_health.

It contains no routing metadata or framework-specific logic. Request binding, HTTP method, and response semantics are defined exclusively by the OpenAPI specification.

"},{"location":"openapi_first/templates/health_app/routes/#openapi_first.templates.health_app.routes.get_health--returns","title":"Returns","text":"

dict A minimal liveness payload indicating service health.

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

OpenAPI-first model-based CRUD application template.

This package contains a complete, minimal example of an OpenAPI-first CRUD service that uses explicit Pydantic domain models for request and response schemas.

The application is assembled exclusively from: - an OpenAPI specification (openapi.yaml) - a handler namespace implementing CRUD operations (routes) - Pydantic domain models (models) - an in-memory mock data store (data)

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.

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

"},{"location":"openapi_first/templates/model_app/#openapi_first.templates.model_app--scaffolding-via-cli","title":"Scaffolding via CLI","text":"

Create a new model-based CRUD example service using the bundled template:

openapi-first model_app\n

Create the service in a custom directory:

openapi-first model_app my-model-service\n

List all available application templates:

openapi-first --list\n

The CLI copies template files verbatim into the target directory. No code is generated or modified beyond the copied scaffold.

"},{"location":"openapi_first/templates/model_app/#openapi_first.templates.model_app--client-usage-example","title":"Client Usage Example","text":"

The same OpenAPI specification used by the server can be used to construct a strict, operationId-driven HTTP client.

Example client calls for model-based CRUD operations:

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

Client guarantees: - One callable per OpenAPI operationId - 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

"},{"location":"openapi_first/templates/model_app/#openapi_first.templates.model_app--non-goals","title":"Non-Goals","text":"

This template is intentionally minimal and is NOT: - production-ready - persistent or concurrency-safe - a reference architecture for data storage

It exists solely as a copyable example for learning, testing, and bootstrapping OpenAPI-first services.

This package is not part of the openapi_first library API surface.

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

In-memory data store using Pydantic models.

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.

The implementation intentionally avoids: - persistence - concurrency guarantees - transactional semantics - validation beyond what Pydantic provides

It is not part of the openapi_first library API surface.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.create_item","title":"create_item","text":"
create_item(payload: ItemCreate) -> Item\n

Create a new item in the data store.

A new identifier is assigned automatically. No additional validation is performed beyond Pydantic model validation.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.create_item--parameters","title":"Parameters","text":"

payload : ItemCreate Data required to create a new item.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.create_item--returns","title":"Returns","text":"

Item The newly created item.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.delete_item","title":"delete_item","text":"
delete_item(item_id: int) -> None\n

Remove an item from the data store.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.delete_item--parameters","title":"Parameters","text":"

item_id : int Identifier of the item to delete.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.delete_item--raises","title":"Raises","text":"

KeyError If the item does not exist.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.get_item","title":"get_item","text":"
get_item(item_id: int) -> Item\n

Retrieve a single item by ID.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.get_item--parameters","title":"Parameters","text":"

item_id : int Identifier of the item to retrieve.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.get_item--returns","title":"Returns","text":"

Item The requested item.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.get_item--raises","title":"Raises","text":"

KeyError If the item does not exist.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.list_items","title":"list_items","text":"
list_items() -> list[Item]\n

Return all items in the data store.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.list_items--returns","title":"Returns","text":"

list[Item] A list of item domain objects.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.update_item","title":"update_item","text":"
update_item(item_id: int, payload: ItemCreate) -> Item\n

Replace an existing item in the data store.

This function performs a full replacement of the stored item. Partial updates are not supported.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.update_item--parameters","title":"Parameters","text":"

item_id : int Identifier of the item to update. payload : ItemCreate New item data.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.update_item--returns","title":"Returns","text":"

Item The updated item.

"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.update_item--raises","title":"Raises","text":"

KeyError If the item does not exist.

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

Application entry point for an OpenAPI-first model-based CRUD example service.

This module constructs a FastAPI application exclusively from an OpenAPI specification and a handler namespace, without using decorator-driven routing.

All HTTP routes, methods, request/response schemas, and operation bindings are defined in the OpenAPI document referenced by openapi_path. Python callables defined in the routes module are bound to OpenAPI operations strictly via operationId.

This module contains no routing logic, persistence concerns, or framework configuration beyond application assembly.

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

This file is intended to be used as the ASGI entry point.

Example

uvicorn main:app

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

Pydantic domain models for the CRUD example.

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.

The models are declarative and framework-agnostic. They contain no persistence logic, validation beyond type constraints, or business behavior.

This module is not part of the openapi_first library API surface. It exists solely to support the example application template.

"},{"location":"openapi_first/templates/model_app/models/#openapi_first.templates.model_app.models.Item","title":"Item","text":"

Bases: ItemBase

Domain model for a persisted item.

This model represents the full item state returned in responses, including the server-assigned identifier.

"},{"location":"openapi_first/templates/model_app/models/#openapi_first.templates.model_app.models.ItemBase","title":"ItemBase","text":"

Bases: BaseModel

Base domain model for an item.

Defines fields common to all item representations.

"},{"location":"openapi_first/templates/model_app/models/#openapi_first.templates.model_app.models.ItemCreate","title":"ItemCreate","text":"

Bases: ItemBase

Domain model for item creation requests.

This model is used for request bodies when creating new items. It intentionally excludes the id field, which is assigned by the service.

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

CRUD route handlers bound via OpenAPI operationId.

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 operationId values.

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.

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.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.create_item","title":"create_item","text":"
create_item(payload: ItemCreate, response: Response)\n

Create a new item.

Implements the OpenAPI operation identified by operationId: create_item.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.create_item--parameters","title":"Parameters","text":"

payload : ItemCreate Request body describing the item to create. response : fastapi.Response Response object used to set the HTTP status code.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.create_item--returns","title":"Returns","text":"

Item The newly created item.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.delete_item","title":"delete_item","text":"
delete_item(item_id: int, response: Response)\n

Delete an existing item.

Implements the OpenAPI operation identified by operationId: delete_item.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.delete_item--parameters","title":"Parameters","text":"

item_id : int Identifier of the item to delete. response : fastapi.Response Response object used to set the HTTP status code.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.delete_item--returns","title":"Returns","text":"

None No content.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.delete_item--raises","title":"Raises","text":"

HTTPException 404 if the item does not exist.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.get_item","title":"get_item","text":"
get_item(item_id: int)\n

Retrieve a single item by ID.

Implements the OpenAPI operation identified by operationId: get_item.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.get_item--parameters","title":"Parameters","text":"

item_id : int Identifier of the item to retrieve.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.get_item--returns","title":"Returns","text":"

Item The requested item.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.get_item--raises","title":"Raises","text":"

HTTPException 404 if the item does not exist.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.list_items","title":"list_items","text":"
list_items()\n

List all items.

Implements the OpenAPI operation identified by operationId: list_items.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.list_items--returns","title":"Returns","text":"

list[Item] A list of item domain objects.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.update_item","title":"update_item","text":"
update_item(item_id: int, payload: ItemCreate)\n

Update an existing item.

Implements the OpenAPI operation identified by operationId: update_item.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.update_item--parameters","title":"Parameters","text":"

item_id : int Identifier of the item to update. payload : ItemCreate New item data.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.update_item--returns","title":"Returns","text":"

Item The updated item.

"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.update_item--raises","title":"Raises","text":"

HTTPException 404 if the item does not exist.

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

End-to-end tests for the OpenAPI-first model CRUD example app.

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

All CRUD operations are exercised against an in-memory mock data store backed by Pydantic domain models.

The tests assume: - OpenAPI-first route binding - Pydantic model validation - In-memory storage (no persistence guarantees) - Deterministic behavior in a single process

"},{"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":"
test_create_item()\n

Creating a new item should return the created entity.

"},{"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":"
test_delete_item()\n

Deleting an item should remove it from the store.

"},{"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":"
test_get_item()\n

Existing item should be retrievable by ID.

"},{"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":"
test_list_items_initial()\n

Initial items should be present.

"},{"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":"
test_update_item()\n

Updating an item should replace its values.

"}]}