Model App

openapi_first.templates.model_app

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

---

Scaffolding via CLI

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

openapi-first model_app

Create the service in a custom directory:

openapi-first model_app my-model-service

List all available application templates:

openapi-first --list

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

---

Client Usage Example

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
from openapi_first.client import OpenAPIClient

spec = load_openapi("openapi.yaml")
client = OpenAPIClient(spec)

# List items
response = client.list_items()

# Get item by ID
response = client.get_item(
    path_params={"item_id": 1}
)

# Create item
response = client.create_item(
    body={"name": "Orange", "price": 0.8}
)

# Update item
response = client.update_item(
    path_params={"item_id": 1},
    body={"name": "Green Apple", "price": 0.6},
)

# Delete item
response = client.delete_item(
    path_params={"item_id": 1}
)

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

---

Non-Goals

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.