doc-api
/octopus:doc-api confronta toda a superfície de API publicada
contra sua spec OpenAPI e o próprio knowledge do repo — on-demand,
não como parte de uma review de diff.
O que resolve
Contract drift aparece em dois eixos: interno (o frontend concorda
com o backend neste diff) e externo (a API publicada ainda bate com
o que a spec e o doc de referência de um integrador prometem, na
superfície inteira). O audit-contracts cobre o primeiro. O
doc-api cobre o segundo — pegando um campo renomeado no código mas
não no openapi.yaml, um error code cuja mensagem mudou sem
atualizar o catálogo, ou um endpoint que silenciosamente parou de
honrar uma regra de negócio que um ADR documenta.
Como resolve
A skill roda em um de dois modos:
- Validate (default) — read-only, full-surface. Reporta drift e mostra um preview do plano por artefato sem tocar em nada.
- Document (
--write) — transforma a avaliação em um plano interativo por artefato (correct/recreate/create/skip) e escreve só os itens escolhidos, atrás de um gate de confirmação.
Os dois modos rodam contra quatro checks, cada um escopado por versão de API detectada (route-explicit, header, query, ou não-versionada):
openapi— conformidade código ↔ spec: endpoints, DTOs, envelopes e status codes presentes no código mas obsoletos ou ausentes na spec, e vice-versa (⚠ Warn/ℹ Info).errors— consistência do catálogo de erros: códigos inconsistentes para a mesma condição, códigos não documentados, mensagens que vazam detalhes internos (⚠ Warn).breaking— mudanças breaking externas, diffadas contra a spec commitada: endpoints removidos ou renomeados, campos removidos, campos com type alterado, auth apertada (🚫 Block).grounding— fidelidade de negócio doc↔código contra ADRs, specs e system maps, reusando o protocolo de fonte de verdade doaudit-grounding(⚠ Warn).
Uso & parâmetros
/octopus:doc-api [--write] [--only=<checks>] [--stacks=<list>] [--spec=<path>] [--out=<path>] [--base=<ref>]--write— troca de validate para document mode: avalia cada artefato e escolhecorrect/recreate/create/skippor item, escrevendo só os escolhidos atrás do gate de confirmação. Default: só validate, read-only.--only=<checks>— subconjunto separado por vírgula deopenapi,errors,breaking,grounding. Default: os quatro.--stacks=<list>— subconjunto das raízes de stack de API detectadas a checar. Default: todas as detectadas.--spec=<path>— sobrescreve a localização da spec OpenAPI. Default: autodetectada (openapi.yaml,openapi.json,swagger.json,docs/openapi.yml, ou config de gerador).--out=<path>— sobrescreve o path de saída do doc de integrador. Default: autodetectado ou confirmado no momento da escrita.--base=<ref>— git ref contra a qual diffar a spec parabreaking. Default: oopenapi.yamlcommitado emHEAD.