DOCS-ADR-002 — Estratégia de Geração de Documentação

Campo	Valor
Status	Aceita
Data	2026-06-17
Decisores	Arquitetura / Plataforma FinWAY
Escopo	Documentação técnica da plataforma FinWAY
Relacionada a	DOCS-ADR-001, Blueprint

Contexto

Adotado o modelo Docs-as-Code (DOCS-ADR-001), resta definir o que é escrito por pessoas e o que é gerado por máquina. A documentação de contrato (endpoints, eventos, modelo de dados) é volumosa, volátil e já existe no código (finway.json e, no futuro, AsyncAPI/schemas). A documentação conceitual (arquitetura, domínio, jornadas, requisitos) exige julgamento humano. Tratar ambos da mesma forma leva a drift ou a documentação sem contexto.

Decisão

A documentação conceitual será escrita manualmente; a documentação de contratos será gerada a partir do código (OpenAPI/AsyncAPI/modelos).

Regra de ouro: conceito é escrito, contrato é gerado. O conteúdo gerado não é editado à mão.

Aplicação por artefato:

• OpenAPI (APIs REST): fonte = static/finway.json (servida também em /finway.json). A API Reference é renderizada em runtime pelo @scalar/docusaurus em /api — não há geração de páginas MDX nem etapa de build dedicada. O contrato não é editado no portal: correções vão ao finway.json na origem. A porção manual (visão do recurso, autenticação, idempotência) usa o template de API. (Mecanismo revisado — ver Atualização.)
• AsyncAPI (Eventos/Webhooks): hoje em finaya-webhooks.md (manual). Médio prazo: descrever em asyncapi.yaml e gerar as páginas (Fase 5). Porção manual via template de evento.
• Modelo de Dados: gerado a partir do schema (Prisma/SQL) — entidades, ERD, índices. Porção manual via template de modelo.
• Runbooks: escritos à mão (template de runbook).
• ADRs: escritos à mão (template de ADR); o portal indexa decisões locais e transversais.

Escrito à mão: Arquitetura, Domínio, Jornadas, Requisitos, Compliance, Runbooks, ADRs. Derivado do código (não editado no portal): OpenAPI (REST) — renderizado em runtime pelo Scalar em /api; AsyncAPI e Modelo de Dados — geração estática, planejados.

Consequências

Positivas

• Contratos sempre fiéis ao código — elimina a principal fonte de drift.
• Reduz esforço manual em conteúdo volumoso/volátil; pessoas focam em contexto e decisões.
• Permite validação automática (lint de OpenAPI/AsyncAPI, detecção de breaking changes).

Negativas / Custos

• Cada serviço precisa produzir e manter seus artefatos de contrato.
• Requer automação de sincronização entre repositórios e portal.
• Correções de contrato vão ao código, não ao portal (mudança cultural).

Neutras

• Conteúdo escrito e gerado convivem com origens e ciclos de vida distintos.
• Marcações visuais devem indicar o que é gerado (para não editar no lugar errado).

Alternativas consideradas

Alternativa	Por que foi descartada
Tudo escrito à mão	Não escala; contratos divergem do código.
Tudo gerado	Inviável para conteúdo conceitual; perde contexto e racional.
Gerar e copiar para o portal manualmente	Reintroduz drift; quebra Single Source of Truth.
Viewer de API isolado por serviço (ex.: Scalar/Swagger standalone, fora do portal)	Sem visão unificada nem navegação cruzada. (O Scalar atualmente adotado roda embutido no portal Docusaurus em /api, preservando a visão unificada — ver Atualização.)

Atualização — 2026-06-19 (mecanismo de OpenAPI)

A decisão acima permanece vigente: conceito é escrito, contrato é derivado do código e não é editado no portal. O que mudou foi o mecanismo de exibição da API Reference REST.

	Antes (decisão substituída)	Agora (vigente)
Renderização	Páginas MDX estáticas geradas no build	Runtime no navegador
Ferramenta	docusaurus-plugin-openapi-docs + docusaurus-theme-openapi-docs	@scalar/docusaurus em /api
Fonte	finway.json (raiz)	static/finway.json (servida em /finway.json)
Artefatos no repo	~514 arquivos .mdx/.json gerados + patch de webpack	nenhum — a spec é lida em runtime
Scripts	gen:api / clean:api	removidos
Interatividade	estática	cliente de testes "try-it-out" embutido

Motivação: eliminar o patch de webpack frágil (BLOCKER exports is not defined) e os arquivos gerados versionados, e ganhar referência interativa. O docusaurus-plugin-openapi-docs fica registrado apenas como decisão substituída, não como arquitetura vigente.

Inalterado: a validação do OpenAPI continua obrigatória via Spectral (npm run validate:openapi, integrado ao npm run ci); o finway.json segue como fonte única da verdade (não editado neste repositório).