Comece pelo contrato

Documentação REST fala com máquinas e pessoas. O contrato descreve paths, métodos, parâmetros, schemas e responses; a camada humana explica intenção, limites e workflows.

O happy path deve ser executável

Mostre autenticação, request completo e response completo para chegar rápido ao primeiro sucesso. Exemplos precisam ser válidos e realistas.

Erros fazem parte da interface

Não pare no 200. Documente falhas de autenticação, validação, conflitos, limites e estados assíncronos, incluindo o próximo passo do cliente.

Separe reference de guides

Reference responde “o que existe?”; guides respondem “como atingir um objetivo?”. Conecte as camadas em vez de criar uma página gigante.

Mantenha exemplos executáveis

Valide JSON, schemas e requests em CI sempre que possível.

OpenAPI é fonte, não a experiência inteira

Use OpenAPI para reference e validação, mas acrescente conceitos, autenticação, limites e cenários end-to-end.

Exemplo aplicado

Transforme “Como documentar uma API REST corretamente” em uma tarefa completa de desenvolvedor. Use um recurso fictício, mas realista, como relatório, dispositivo ou pedido, e descreva o caminho mais curto da autenticação ao resultado correto. Inclua request, campos importantes da response, uma falha provável e a próxima ação depois dela.

Revise como se fosse implementar um cliente:

  • quais valores o desenvolvedor precisa substituir;
  • quais identificadores o servidor devolve e serão reutilizados;
  • qual status ou campo confirma sucesso;
  • o que fazer diante de credenciais, entrada ou limite incorretos.

Documentação de API funciona quando permite prever a interação com o sistema, não apenas reconhecer nomes de endpoints.

Checklist editorial rápido

  • Comece pelo contrato. Documentação REST fala com máquinas e pessoas.
  • O happy path deve ser executável. Mostre autenticação, request completo e response completo para chegar rápido ao primeiro sucesso.
  • Erros fazem parte da interface. Não pare no 200. Documente falhas de autenticação, validação, conflitos, limites e estados assíncronos, incluindo o próximo passo do cliente.
  • Separe reference de guides. Reference responde “o que existe?”; guides respondem “como atingir um objetivo?”.

Leituras relacionadas