Contrato de API¶

A fonte de verdade do contrato é o Swagger gerado pela própria API em runtime, não um arquivo estático neste repositório — apps/api/CLAUDE.md exige que todo endpoint tenha summary, description e response_description no decorator, atualizados no mesmo PR que muda o comportamento.

Por que não há um openapi.yaml estático aqui¶

Não há snapshot versionado do contrato, e isso é de propósito: um arquivo estático envelhece a cada endpoint novo sem que ninguém perceba, e o único cliente da API hoje é o apps/web, versionado junto no monorepo. O canal de consulta é o endpoint ao vivo — para agentes, pelo skill api-docs, que guarda um cache em .claude/skills/api-docs/openapi.json (gerado sob demanda a partir do ambiente local, e renovado só quando se pede).

Se um dia for preciso entregar um arquivo — a integrador externo, por exemplo —, o snapshot se gera do dev-remote:

curl -s https://dev.garantora.com.br/api/openapi.json | \
  python3 -c "import sys, json, yaml; yaml.safe_dump(json.load(sys.stdin), sys.stdout, allow_unicode=True)" \
  > docs/api/openapi.yaml

Gerado, ele é o snapshot publicado de um momento, não a fonte da verdade.

Convenções do contrato¶

• Permissão por endpoint — formato resource:action (ex. credit-analyses:approve), exigida via require_permission()/require_any_permission(). Ver ../architecture/components.md.
• 404 vs. 403 — registro de outro tenant é 404, nunca 403. Ver ../architecture/data-model.md.
• Swagger completo — make preflight recusa endpoint novo sem summary, description e response_description.
• Migrations documentam downgrade — é o caminho de volta de um deploy ruim (ver ../operations/deployment.md).

O contrato de cada funcionalidade nova está descrito na seção 12 ("Contrato de API") da spec correspondente, em ../specifications/ — escrita sobre o template ../doc-templates/specification.md.