OpenAPI

La fuente de verdad de la API REST es la spec OpenAPI 3.1 servida en:

• Producción: https://api.wiservet.com/api/v1/openapi.yaml
• Repo: spec/openapi.yaml

Cómo se mantiene en sync

CI (.github/workflows/openapi-lint.yml) corre en cada PR:

1. Spectral lint: estilo OWASP + Wiservet rules (.spectral.yml).
2. oapi-codegen: genera stubs Go en backend/internal/api/.
3. openapi-typescript: genera tipos TS en frontend/src/types/api.ts.
4. Diff check: si hay drift entre spec y código generado → CI rojo.

Renderers recomendados

• Swagger UI local: npx @redocly/cli preview-docs spec/openapi.yaml
• Stoplight Studio: editor visual .yaml
• Postman: importa el .yaml para colección lista

Versionado

• URL path /api/v1/. Breaking changes → /api/v2/.
• Deprecation: header Sunset: <date RFC7231> 6 meses antes de remover.
• Changelog: GitHub releases.