final-openapi-contract-review

name	final-openapi-contract-review
description	Project-specific workflow for OpenAPI, API DTO, schema-shape, and frontend/backend contract review in this FastAPI + React clinic system. Use when adding or changing API endpoints, /api/v1/ui screen/read-model DTOs, generated OpenAPI shape, frontend API adapters, contract tests, or schema assertions.

Final OpenAPI Contract Review

Use this skill when an API change needs a provable contract, especially before or during BFF-lite /api/v1/ui/* read-model work.

This is a local repo-specific contract discipline. External OpenAPI/Speakeasy-style guidance may inspire the approach, but the authoritative evidence is this repo's FastAPI app, Pydantic schemas, tests, and frontend API usage.

Context Gate

Read the smallest relevant set:

• AGENTS.md
• .ai-factory/ARCHITECTURE.md
• backend endpoint, service, schema, and test files for the changed route
• frontend API adapter or screen consuming the route
• backend/tests/test_openapi_contract.py
• related frontend contract/API tests under frontend/src/api or screen tests

For /api/v1/ui/* endpoints, also use final-bff-lite-read-model. For frontend-owned business decisions, use final-ssot-contract-repair first.

Contract Checklist

For every route or DTO change, prove:

• The route is published in FastAPI OpenAPI unless intentionally private.
• Request and response schemas are explicit Pydantic models, not loose dicts where a DTO is needed.
• Required, nullable, enum/status, list, pagination, and error shapes are intentional.
• Sensitive fields are redacted from OpenAPI-visible response models.
• Operation IDs are stable and duplicate-free.
• Frontend adapters consume the documented shape without fallback guessing.
• Tests cover the exact schema shape the frontend relies on.

UI Read-Model DTO Rules

For BFF-lite screen endpoints:

• Name schemas under backend/app/schemas/ui/ when added.
• Keep DTOs read-only unless the route is explicitly a command wrapper.
• Include available_actions only when calculated by core services.
• Include canonical IDs and record types from backend sources; do not force React to infer them.
• Include display-safe status facts, but keep state transitions in core services.
• Prefer one focused screen DTO over broad generic dashboard payloads.

Validation Targets

Prefer narrow checks:

• backend/tests/test_openapi_contract.py
• route-specific backend pytest
• frontend API adapter tests
• component/screen tests using realistic DTO fixtures
• OpenAPI duplicate operation ID check

If a route is security-sensitive, also prove auth/role behavior and redaction.

Output

Report:

• Route or DTO reviewed
• Contract source of truth
• OpenAPI visibility
• Schema-shape assertions
• Frontend consumer impact
• Tests run or proposed
• Contract gaps before merge