Documentación de la API
Reglas
- Especificación OpenAPI 3.1 como fuente única de verdad — generar desde el código, no escrita manualmente
- Esquemas Zod a OpenAPI: usar
zod-openapi o @asteasolutions/zod-to-openapi — definir una vez, validar y documentar
- Documentación interactiva: Scalar (moderno, rápido) o Swagger UI — servir en
/docs o /api-docs
- Cada endpoint debe tener: resumen, descripción, esquema del cuerpo de la petición, todos los códigos de respuesta con ejemplos
- Petición/respuesta de ejemplo para cada endpoint — usar datos realistas, no marcadores de posición como
"string"
- Estrategia de versionado: ruta URL (
/api/v1/, /api/v2/) para cambios disruptivos — más simple que el versionado por cabecera
- Respuestas de error: documentar todas las formas de error de manera consistente —
{ error: string, code: string, details?: object }
- Autenticación: documentar el esquema de autenticación (Bearer token, clave API) en la sección de esquemas de seguridad
- Agrupar endpoints por recurso:
/users, /products, /orders — usar etiquetas para agrupar en la interfaz de documentación
Patrones
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: "Crear un usuario",
request: { body: { content: { "application/json": { schema: CreateUserSchema } } } },
responses: {
201: { description: "Usuario creado", content: { "application/json": { schema: UserSchema } } },
400: { description: "Error de validación" },
},
});
Evitar
- Escribir YAML de OpenAPI a mano — generar desde esquemas Zod o definiciones de ruta
- Omitir la documentación de respuestas de error — documentar 400, 401, 403, 404, 500
- Ejemplos genéricos como
"string" o 0 — usar valores realistas que muestren la forma de los datos reales
- Documentación que se desvía de la implementación — generar la especificación a partir de los mismos esquemas utilizados para la validación