Válido é só o começo
Um exemplo derivado do schema pode estar sintaticamente correto e não ensinar nada. string, 123 e foo passam por validadores, mas escondem o domínio. Um bom exemplo mostra por que a request existe e o que o resultado permite fazer.
Use valores realistas sem expor secrets ou dados pessoais reais.
Construa uma pequena narrativa
Prefira uma sequência parecida com uma tarefa real: criar um recurso, consultá-lo, atualizar e lidar com falha ou limpeza. Reutilize identificadores para mostrar relações.
Em páginas de reference, ligue ao workflow relevante em vez de duplicar um tutorial inteiro.
Mostre a resposta importante
Não pare na request. Inclua status, headers relevantes e body. Explique campos pouco óbvios. Em operações assíncronas, mostre como o client descobre que o trabalho terminou.
Erros merecem o mesmo cuidado: um validation error realista pode ensinar mais que outro happy path.
Torne exemplos executáveis
Quando possível, rode requests no CI ou valide payloads contra o contrato. Guarde samples como arquivos ou snippets gerados, não como cópias manuais espalhadas.
Otimize para adaptação
Explique que valores devem ser alterados e que pressupostos devem continuar verdadeiros. O objetivo é transferir um modelo mental.
Se o exemplo não facilita a próxima chamada, provavelmente é decoração.
Exemplo aplicado
Transforme “Exemplos de API devem ensinar um fluxo, não decorar a referência” 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
- Válido é só o começo. Um exemplo derivado do schema pode estar sintaticamente correto e não ensinar nada.
- Construa uma pequena narrativa. Prefira uma sequência parecida com uma tarefa real: criar um recurso, consultá-lo, atualizar e lidar com falha ou limpeza.
- Mostre a resposta importante. Não pare na request. Inclua status, headers relevantes e body.
- Torne exemplos executáveis. Quando possível, rode requests no CI ou valide payloads contra o contrato.
