ADR-063 — OpenAPI workflow

Architecture decision record — status: Accepted.

Source: docs/adr/ADR-063-openapi-workflow.md

ADR-063: OpenAPI workflow

Estado

Accepted — 2026-08-23

Decisión

  1. Fuente: packages/api-contract/openapi.yaml (ADR-012).
  2. Contrato primero en changes de API: actualizar YAML en el mismo PR que el controller.
  3. CI: validar spec + (cuando exista) diff breaking.
  4. Web/api client se genera o se tipe a mano desde el spec — se elige tipos generados en el scaffold (openapi-typescript o equivalente). No DTOs divergentes.
  5. No portal apps/docs en V1 (IVPrior FEAT-080). Swagger UI opcional en api local.

Breaking change: bump /api/v1 no se hace a la ligera; preferir campos nuevos. Si hay breaking: changelog (breaking) (ADR-053).