doc-api
doc-api mira um modo de falha diferente do audit-contracts: não
“o frontend concorda com o backend” e sim “a API publicada ainda bate
com o que a spec OpenAPI — e o doc de referência que um integrador
externo lê — promete.” Um check de contract drift interno pode passar
limpo enquanto a superfície voltada ao integrador apodrece em
silêncio: um campo renomeado no código mas não na spec, um error code
que mudou de mensagem sem atualizar o catálogo, uma regra de negócio
que um ADR documenta e que o endpoint não honra mais.
Dois modos
- Validate (default) — read-only, full-surface. Confronta toda a API contra a spec OpenAPI existente e o próprio knowledge do repo — ADRs, specs, CONTEXT.md, system maps — reporta o drift e mostra um preview do mesmo plano por artefato sem escrever nada.
- Document (
--write) — transforma essa avaliação em um plano interativo, por artefato: para cada artefato você escolhe corrigir no lugar, recriar do zero, criar se estiver faltando, ou pular — e só os itens escolhidos são escritos. Só roda quando explicitamente pedido, e nunca escreve sem confirmação.
Os quatro checks
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 em drift, Info para superfície só-na-spec ou só-no-código.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. Adicionar uma nova versão de API não é breaking; mudar uma existente é.grounding— fidelidade de negócio doc↔código, reusando o protocolo de fonte de verdade doaudit-groundingem vez de reimplementá-lo: confronta o catálogo de erros e a semântica dos endpoints contra ADRs, specs e system maps. Warn.
Escopado por versão de API
APIs reais raramente têm uma superfície única e plana — a maioria
carrega um esquema de versionamento, seja um segmento de rota /v1/,
um header, um query param, ou nenhum. doc-api detecta qual esquema
está em jogo e marca cada endpoint com sua versão resolvida. Quando
versões coexistem, todo check — incluindo breaking — roda por
versão: um endpoint /v1 e um /v2 são contratos distintos com
baselines distintas, e os findings e a referência gerada são
agrupados de acordo. Uma superfície não versionada é só o caso de
versão única.
O write gate é um plano por artefato
--write nunca toca código de aplicação — só a spec OpenAPI e a
referência para integradores. Em vez de regenerar tudo atrás de um
único gate all-or-nothing, ele apresenta um plano por artefato e por
versão construído a partir da mesma avaliação que o report de validate
mostra. Cada artefato carrega um estado — absent, stale ou ok —
derivado dos quatro checks, e as ações que fazem sentido para ele:
correct— um patch cirúrgico mínimo que fecha o drift que os checks acharam, preservando prosa, ordem e exemplos escritos à mão. Para uma referência curada que só ficou obsoleta em pontos.recreate— um rebuild inteiro a partir do contrato do código, descartando a estrutura existente. Para um doc tão divergente que remendar vira ruído.create— um caminho de primeira classe para um artefato que ainda não existe, de modo que bootstrapar docs de uma API não documentada é um item do plano, não um branch de erro.skip— deixa intocado.
Os paths de saída são autodetectados primeiro, com default em seguida,
e qualquer layout legado detectado é oferecido como default para
preservar convenções existentes. O check breaking anota a ação que
você escolhe — marcando-a com 🚫 e a mudança específica antes de
aplicá-la — para que nada breaking seja escrito em silêncio. O gate
mostra o diff de cada item escolhido e então escreve só esses itens
mediante confirmação.
Contraste com audit-contracts
audit-contracts e doc-api parecem adjacentes mas respondem
perguntas diferentes em eixos diferentes. audit-contracts é
interno: a mudança de backend deste diff bate com o consumer de
frontend, escopado ao que mudou. doc-api é externo: a superfície
publicada inteira ainda bate com o que a spec OpenAPI e o doc de
referência de um integrador prometem, escopado a tudo — o que também
explica por que doc-api roda on-demand em vez de fazer parte do
audit-all: um check full-surface, reasoning-tier, que ocasionalmente
escreve, não pertence ao mesmo lote paralelo dos audits escopados a
diff.
Suporte a stacks
Hoje a skill entende stacks de API em .NET e Node.js — a extração de endpoints, DTOs e convenções de rota é stack-aware nas duas.