Un schema responde a una clase concreta de preguntas
OpenAPI describe muy bien operaciones, parámetros, estructuras de request y response, status codes y schemas reutilizables. Por eso es una excelente fuente para reference generado y validación automática.
El problema aparece cuando se asume que un schema completo produce automáticamente una documentación completa.
El developer necesita un recorrido
Antes de mirar cada campo, una persona nueva pregunta cómo autenticarse, qué entorno usar, cuál es la petición mínima, cómo se relacionan los recursos y cómo manejar retries. Esas respuestas pertenecen a contenido conceptual y orientado a tareas conectado con la referencia.
Los ejemplos transmiten semántica
Un schema puede decir que un campo es string. Un buen ejemplo muestra un valor realista, cómo interactúan los campos y qué devuelve el servidor. Valida los ejemplos cuando sea posible y mantenlos cerca del contrato para que los cambios sean visibles en review.
Documenta el fallo como un camino principal
La referencia generada suele enumerar errores sin enseñar recuperación. Explica qué errores permiten retry, cuáles indican estado inválido, cómo se comunica un rate limit y qué identificadores necesita soporte.
No inventes garantías. Si idempotencia o retries no están claros, es una pregunta de producto.
Usa OpenAPI para lo que hace mejor
Genera datos de campos y estructura desde la especificación, valida ejemplos y evita duplicación. Dedica el trabajo editorial a modelos mentales, workflows, trade-offs y recuperación.
La mejor documentación trata el schema como evidencia y el sitio publicado como una experiencia construida alrededor de esa evidencia.
Ejemplo aplicado
Convierte «OpenAPI es una fuente de verdad, no toda la documentación de la API» 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
- Un schema responde a una clase concreta de preguntas. OpenAPI describe muy bien operaciones, parámetros, estructuras de request y response, status codes y schemas reutilizables.
- El developer necesita un recorrido. Antes de mirar cada campo, una persona nueva pregunta cómo autenticarse, qué entorno usar, cuál es la petición mínima, cómo se relacionan los recursos y cómo manejar retries.
- Los ejemplos transmiten semántica. Un schema puede decir que un campo es string.
- Documenta el fallo como un camino principal. La referencia generada suele enumerar errores sin enseñar recuperación.
