Documentação de API
Regras
- Especificação OpenAPI 3.1 como fonte única da verdade — gerar a partir do código, não escrita manualmente
- Esquemas Zod para OpenAPI: usar
zod-openapi ou @asteasolutions/zod-to-openapi — definir uma vez, validar e documentar
- Documentação interativa: Scalar (moderno, rápido) ou Swagger UI — servir em
/docs ou /api-docs
- Cada endpoint deve ter: resumo, descrição, esquema do corpo da requisição, todos os códigos de resposta com exemplos
- Exemplo de requisição/resposta para cada endpoint — usar dados realistas, não placeholders como
"string"
- Estratégia de versionamento: caminho de URL (
/api/v1/, /api/v2/) para mudanças que quebram compatibilidade — mais simples que versionamento por cabeçalho
- Respostas de erro: documentar todas as formas de erro consistentemente —
{ error: string, code: string, details?: object }
- Autenticação: documentar esquema de autenticação (Bearer token, chave de API) na seção de security schemes
- Agrupar endpoints por recurso:
/users, /products, /orders — usar tags para agrupar na interface de documentação
Padrões
import { z } from "zod";
import { extendZodWithOpenApi } from "@asteasolutions/zod-to-openapi";
extendZodWithOpenApi(z);
const UserSchema = z.object({
id: z.string().uuid().openapi({ example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }),
name: z.string().openapi({ example: "Jane Smith" }),
email: z.string().email().openapi({ example: "[email protected]" }),
}).openapi("User");
const CreateUserSchema = UserSchema.omit({ id: true }).openapi("CreateUser");
registry.registerPath({
method: "post",
path: "/api/v1/users",
summary: "Criar um usuário",
request: { body: { content: { "application/json": { schema: CreateUserSchema } } } },
responses: {
201: { description: "Usuário criado", content: { "application/json": { schema: UserSchema } } },
400: { description: "Erro de validação" },
},
});
Evitar
- Escrever YAML do OpenAPI manualmente — gerar a partir de esquemas Zod ou definições de rota
- Documentação de resposta de erro ausente — documentar 400, 401, 403, 404, 500
- Exemplos genéricos como
"string" ou 0 — usar valores realistas que mostrem a forma dos dados reais
- Documentação que se desvia da implementação — gerar especificação a partir dos mesmos esquemas usados para validação