Documentação de microserviços: o mínimo para não perder o controle

Por que microserviços exigem doc diferente

Num monolito, arquitetura cabe em três diagramas e um README. Em uma arquitetura distribuída com 15, 40, 200 serviços, cada time começa a documentar do seu jeito. Em pouco tempo você tem 40 páginas Confluence desatualizadas e nenhuma resposta pra "quem consome o endpoint /api/v2/orders?".

A solução não é mais documentação — é padrão + automação. Padrão pra que cada serviço documente as mesmas coisas. Automação pra que o mínimo seja gerado a partir do código, não digitado à mão.

O padrão service.md — mínimo obrigatório por serviço

Adote a regra: todo repositório de serviço tem um service.md na raiz, com estas seções, sempre nesta ordem:

# orders-service

## Responsabilidade
Uma frase. "Guarda pedidos, calcula totais e emite eventos de pedido criado."

## Owner
Time: @squad-checkout
On-call: PagerDuty schedule "checkout-primary"

## APIs expostas
- REST: /api/v2/orders (OpenAPI em ./openapi.yaml)
- Async: emite `order.created`, `order.paid`, `order.canceled` no tópico Kafka `orders`

## Dependências
- Postgres (dedicado — instância orders-db)
- Payments-service (síncrono, gRPC)
- Kafka (assíncrono, produção e consumo)

## Consumidores conhecidos
- billing-service (consome order.paid)
- analytics-worker (consome todos os eventos)
- notification-service (consome order.created)

## Runbook
docs/runbook.md (o que fazer quando 5xx, quando lag no Kafka, etc.)

## Decisões arquiteturais
docs/adr/ (histórico de ADRs específicos deste serviço)

As 3 coisas que precisam existir centralizadas

Além do service.md por repo, três artefatos vivem no nível da organização:

1. Service catalog. Uma lista viva de todos os serviços com owner, stack e link pro repo. Backstage (Spotify), Cortex e Port são as ferramentas dominantes. Numa escala menor, uma tabela num README organizacional já resolve.
2. Diagrama de contêineres C4 do sistema todo. Um único diagrama que mostra todos os serviços e as principais integrações entre eles. Deve ser gerado a partir do service catalog, não desenhado à mão — do contrário desatualiza em uma sprint.
3. Mapa de eventos (event catalog). Se você usa mensageria, precisa listar cada tópico/evento, o produtor e todos os consumidores. Sem isso, ninguém consegue evoluir um schema com segurança. Ferramentas: EventCatalog, AsyncAPI.

Automatize o que der pra automatizar

• OpenAPI — gere a partir de anotações no código, não escreva à mão.
• AsyncAPI — mesma ideia para eventos.
• Dependency graph — extraia dos arquivos de config (docker-compose, IaC, service mesh) em vez de manter um diagrama estático.
• Service catalog — Backstage descobre serviços a partir de arquivos catalog-info.yaml em cada repo.

O papel dos ADRs em arquitetura distribuída

Em microserviços, decisões cruzam times. Escolher entre eventual consistency e saga, entre REST e gRPC, entre extrair um novo serviço ou expandir um existente — tudo isso são ADRs obrigatórios. Sem eles, cada squad toma decisões conflitantes e você acorda com 3 formatos diferentes de autenticação interserviço.

O antipadrão mais comum

Diagrama arquitetural "oficial" em Confluence, desenhado em ferramenta visual, exportado como PNG. Ele nasce lindo, envelhece rápido, e ninguém tem coragem de refazer — porque o autor original saiu da empresa e o arquivo .drawio original se perdeu. A solução é o oposto: diagrama como código, versionado junto com o serviço, revisado no mesmo PR que muda o comportamento.

Checklist mínimo

• [ ] Todo serviço tem service.md no padrão da org.
• [ ] OpenAPI/AsyncAPI gerados no CI, publicados em um catálogo central.
• [ ] Service catalog com owner e on-call de cada serviço.
• [ ] Diagrama de contêineres C4 versionado como código.
• [ ] Pasta docs/adr/ em todo repo relevante.
• [ ] Runbook por serviço com os 5 alertas mais comuns e como responder.