Escribir la parte que el generador no puede
La documentación generada responde «qué recibe este endpoint». Nadie se quedó nunca atascado en esa pregunta.
API Documentation genera desde tus colecciones y encima te da un editor de texto enriquecido, gestión de versiones, generación de fragmentos de código, exportación a PDF y enlaces compartibles.
La mitad generada es completa y correcta y, por sí sola, no ayuda a nadie. Lo que bloquea a un desarrollador nunca es la lista de parámetros.
Ordena el documento para quien lee por primera vez
Las listas de endpoints suelen ser alfabéticas, que es el orden que no sirve a nadie. Ordena el documento como se integra:
- Cómo autenticarse, con un ejemplo completo que funcione.
- La llamada que demuestra que la configuración va — la petición más pequeña que devuelva algo.
- El flujo principal, en el orden en que ocurre.
- Todo lo demás, alfabéticamente, porque a esas alturas quien lee ya está buscando, no leyendo.
Quien llega a una primera llamada exitosa se vuelve paciente. Quien no consigue autenticarse en diez minutos escribe a soporte y se queda molesto.
Documenta los errores, no el éxito
Toda documentación generada describe el 200. Casi ninguna describe el 409 que significa que el correo ya está registrado, ni qué debe hacer el cliente: reintentar, mostrar un mensaje o recurrir a otra llamada.
Escribe la tabla de errores a mano. Es la sección más leída y la única que acorta las conversaciones con soporte.
Cuándo cortar una versión
La gestión de versiones se gana su sitio el día en que alguien de fuera de tu equipo construye contra la API. Corta una versión en ese momento, no en un hito de release.
La razón es práctica: cuando cambies un campo más adelante, quien integró el trimestre pasado necesita el documento tal como estaba, no una entrada de changelog explicando que se movió. Compartir un enlace a una versión concreta no cuesta nada y zanja la discusión antes de que exista.
Para cualquier cosa con lectores externos, comparte un enlace en vez de exportar PDF. El enlace sigue la versión; un PDF empieza a estar mal al día siguiente de enviarlo.
Preguntas que la gente hace
¿En qué orden debe ir la documentación?
Autenticación con ejemplo completo, luego la llamada más pequeña que demuestre que funciona, luego el flujo principal en secuencia, y después todo lo demás alfabéticamente. Alfabético desde arriba no sirve a nadie que integre por primera vez.
¿Qué debo escribir a mano?
Los errores y por qué existe cada endpoint. El generador cubre los parámetros por completo; nadie se atascó nunca en una lista de parámetros y todo el mundo se ha atascado en un 409 sin explicar.
¿Cuándo debo cortar una versión nueva?
El día en que alguien de fuera de tu equipo empieza a construir contra la API, no en un hito de release. Esa persona necesitará el documento tal como estaba al integrar, no una nota diciendo que un campo se movió.
