Empieza por el contrato
La documentación REST tiene dos audiencias: máquinas y personas. El contrato describe paths, métodos, parámetros, schemas y responses; la documentación humana explica intención, límites y flujos.
El happy path debe ser ejecutable
Muestra autenticación, request completo y response completo para que el primer éxito sea rápido. Los ejemplos deben ser válidos y realistas.
Los errores son parte de la interfaz
No termines en 200. Documenta autenticación, validación, conflictos, límites y estados asíncronos. Explica qué puede hacer el cliente después.
Separa reference y guides
Reference responde “¿qué existe?” y los guides “¿cómo logro un objetivo?”. Conecta ambos con enlaces en lugar de hacer una página inmanejable.
Mantén ejemplos ejecutables
Valida JSON, schemas y requests en CI cuando sea posible. Los ejemplos rotos destruyen confianza.
OpenAPI es una fuente, no toda la experiencia
Úsalo para reference y validación, pero añade conceptos, autenticación, límites y escenarios end-to-end. Buena documentación permite predecir el sistema antes de llamarlo.
Ejemplo aplicado
Convierte «Cómo documentar correctamente una API REST» en una tarea completa de desarrollador. Usa un recurso ficticio pero realista, como un informe, dispositivo o pedido, y describe el camino más corto desde la autenticación hasta un resultado correcto. Incluye la petición, los campos importantes de la respuesta, un fallo probable y la siguiente acción después de ese fallo.
Revisa el ejemplo como si fueras a construir un cliente con él:
- qué valores debe sustituir el desarrollador;
- qué identificadores devuelve el servidor y se reutilizan después;
- qué estado o campo confirma el éxito;
- qué debe hacer el cliente ante credenciales, datos o límites incorrectos.
La documentación de API es útil cuando permite predecir la interacción con el sistema, no solo reconocer nombres de endpoints.
Lista rápida de revisión editorial
- Empieza por el contrato. La documentación REST tiene dos audiencias: máquinas y personas.
- El happy path debe ser ejecutable. Muestra autenticación, request completo y response completo para que el primer éxito sea rápido.
- Los errores son parte de la interfaz. No termines en 200. Documenta autenticación, validación, conflictos, límites y estados asíncronos.
- Separa reference y guides. Reference responde “¿qué existe?” y los guides “¿cómo logro un objetivo?”.
