Vishesh 'ironeagle' Bangotra
a3c063b569
- Add comprehensive module and function docstrings to crud_app and model_app templates - Document OpenAPI-first guarantees, non-goals, and usage patterns in templates - Add template-level __init__.py files with CLI and client usage examples - Update mkdocs.yml to include CRUD and model-based CRUD template documentation - Ensure template documentation follows strict package-bound mkdocstrings rules
103 lines
3.2 KiB
Python
103 lines
3.2 KiB
Python
"""
|
|
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.
|
|
"""
|