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