98 lines
3.7 KiB
Python
98 lines
3.7 KiB
Python
"""
|
|
OpenAPI-first Veterinary Clinic application template.
|
|
|
|
This package contains a complete, runnable example of an OpenAPI-first
|
|
veterinary clinic management service. It demonstrates all ``x-`` extension
|
|
fields consumed by the ``react-openapi`` admin panel renderer.
|
|
|
|
The application manages five resources:
|
|
|
|
- **Parents** — pet owners with contact details
|
|
- **Vets** — veterinarians with specializations
|
|
- **Treatments** — medical procedure catalog
|
|
- **Pets** — animals with species, age, weight, and photos
|
|
- **Appointments** — scheduled visits linking pets, vets, and treatments
|
|
|
|
All HTTP routes, methods, schemas, and operation bindings are defined
|
|
in the OpenAPI specification (``openapi.yaml``). Every operation has an
|
|
explicit ``operationId`` that maps to a Python handler in ``routes.py``.
|
|
|
|
This file is a copyable template. It is not part of the ``openapi_first``
|
|
library API surface.
|
|
|
|
----------------------------------------------------------------------
|
|
OpenAPI x- extension fields demonstrated
|
|
----------------------------------------------------------------------
|
|
|
|
Schema-level extensions (mark a schema as a UI resource):
|
|
|
|
``x-resource`` (REQUIRED) Maps schema to URL path segment
|
|
``x-primary-key`` (REQUIRED) Primary key property name
|
|
``x-display-format`` (REQUIRED) Human-readable label template
|
|
``x-list-columns`` (REQUIRED) Columns for the datatable
|
|
|
|
Property-level extensions (control UI rendering):
|
|
|
|
``x-label`` (REQUIRED) Human-readable field label
|
|
``x-order`` (REQUIRED) Field ordering in forms/detail
|
|
``x-description`` (optional) Helper text below form fields
|
|
``x-hidden`` (optional) Visibility in form / list / detail
|
|
``x-filterable`` (optional) Allows column filtering
|
|
``x-sortable`` (optional) Allows column sorting
|
|
``x-fk`` (optional) Foreign key — renders as dropdown
|
|
``x-fk.resource`` (REQUIRED for FK) Target resource name
|
|
``x-fk.prefetch`` (optional) Preload all FK options on mount
|
|
``x-ui-type`` (optional) Custom UI type (e.g. image upload)
|
|
``x-upload-url`` (optional) Upload endpoint for binary fields
|
|
|
|
----------------------------------------------------------------------
|
|
Scaffolding via CLI
|
|
----------------------------------------------------------------------
|
|
|
|
Create a new vet clinic service using the bundled template:
|
|
|
|
openapi-first vet_app
|
|
|
|
Create the service in a custom directory:
|
|
|
|
openapi-first vet_app my-vet-clinic
|
|
|
|
----------------------------------------------------------------------
|
|
Client Usage Example
|
|
----------------------------------------------------------------------
|
|
|
|
from openapi_first.loader import load_openapi
|
|
from openapi_first.client import OpenAPIClient
|
|
|
|
spec = load_openapi("openapi.yaml")
|
|
client = OpenAPIClient(spec)
|
|
|
|
# List pets with pagination
|
|
response = client.list_pets(query_params={"limit": 10, "offset": 0})
|
|
|
|
# Create a pet with FK references
|
|
response = client.create_pet(
|
|
body={"name": "Fido", "species": "dog", "parents": [1, 2]}
|
|
)
|
|
|
|
# Upload a pet photo
|
|
response = client.upload_pet_photo(
|
|
path_params={"id": 1},
|
|
body={"file": open("photo.jpg", "rb")},
|
|
)
|
|
|
|
----------------------------------------------------------------------
|
|
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.
|
|
"""
|