De una petición a documentación que alguien lee
La documentación de API se pudre porque se escribe aparte de las peticiones. Generarla desde la colección es la única versión que sigue siendo cierta.
La mayoría de la documentación de API miente hacia el tercer mes. No porque nadie mintiera, sino porque la documentación vive en un sitio y las peticiones en otro, y solo una de las dos se actualiza cuando cambia un campo.
Lodos cierra ese hueco generando la documentación a partir de la colección contra la que ya estás probando. Ese es todo el sentido de tener los dos módulos juntos, y cambia cómo deberías organizar la colección desde el primer día.
Organiza la colección para la documentación, no para ti
API Post/Get admite todos los métodos HTTP, colecciones con carpetas, gestión de cabeceras y autorización, y un visor de respuestas con resaltado de sintaxis. La estructura de carpetas que elijas será la estructura de tu documentación, así que merece cinco minutos de reflexión.
Agrupa por recurso, no por tarea. Una carpeta llamada users con listar, crear, actualizar y borrar se lee como documentación. Una carpeta llamada flujo de alta con tres peticiones de tres recursos distintos se lee como tu cuaderno personal, porque eso es.
Nombra las peticiones con el vocabulario de la propia API. GET /users/:id es mejor que obtener un usuario, porque quien lee la documentación intenta emparejar lo que ve con el endpoint que está llamando.
Las variables de entorno son lo que la hace sobrevivir
Esa es la diferencia entre una colección que dura un año y otra que deja de funcionar la primera vez que staging se mueve.
Mete cada host, cada token y cada identificador cambiante en una variable de entorno. {{base_url}}/users/{{test_user_id}} es una petición que funciona contra local, staging y producción cambiando un desplegable. Una petición con https://staging-2.example.com incrustado en la URL es una petición que se rompe en silencio en tres semanas y que reescribe quien la necesite después.
Los scripts previos resuelven el caso que más atasca: un token de autorización que caduca. Pídelo en un paso previo y guárdalo en una variable de entorno, y dejarás de pegar un bearer nuevo en once peticiones cada mañana.
Credenciales, con honestidad
Una colección pertenece al espacio de trabajo, lo que significa que todo el que tenga acceso puede verla, incluidos los valores de tus entornos.
Trátalo como la restricción de diseño que es. Credenciales de desarrollo y staging en la colección están bien y son genuinamente útiles: quien recoja tu trabajo no debería tener que buscarlas. Las de producción no están bien. Si un valor sería un problema en una captura de pantalla, no debe estar en un entorno compartido.
El montaje práctico: un entorno por etapa, con producción deliberadamente incompleta para que lanzar contra ella exija un acto consciente y no una selección equivocada en un desplegable.
Convertirlo en documentación
API Documentation genera desde la colección 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 parte generada cubre qué es el endpoint y qué recibe. Lo que no puede saber es por qué alguien lo llamaría, y esa es justo la parte que necesita quien lee. Así que el patrón que funciona:
- Genera desde la colección. No escribas la lista de endpoints a mano; se desviará.
- Añade un párrafo corto por recurso explicando para qué sirve y cuándo lo usarías.
- Documenta los errores. No el 200: el 409 que significa que el correo ya está cogido, y qué debe hacer el cliente al respecto.
- Publica un enlace en vez de exportar un PDF, salvo que alguien necesite específicamente un archivo. Un enlace sigue siendo actual; un PDF es la fotografía de un momento.
La gestión de versiones importa cuando tienes consumidores externos. Corta una versión en el punto en que alguien empieza a construir contra ella, para que cuando cambies algo siga existiendo un documento que describa aquello contra lo que construyó.
Las 130 cosas pequeñas
Vale la pena saberlo porque ahorra una pestaña: el módulo Tools tiene más de 130 utilidades — formateadores de JSON y XML, codificadores, conversores, generadores de hash. Se ejecutan enteramente en tu navegador, no se sube nada y no cuestan tokens.
Ese último detalle pesa más de lo que parece. Pegar un payload en un formateador JSON online cualquiera es pegar tus datos en el servidor de otra persona. Si el payload lleva datos de un cliente, es un pequeño incidente que nadie va a notar nunca. La herramienta local elimina la tentación.
Preguntas que la gente hace
¿Puedo importar una colección existente?
Las colecciones se construyen en API Post/Get con carpetas, cabeceras, autorización y entornos. Si vienes de otra herramienta, reconstruye las peticiones que usas de verdad en lugar de importarlo todo: casi todas las colecciones arrastran años de endpoints muertos que nadie llama.
¿Quién puede ver las credenciales de mis entornos?
Todo el que tenga acceso al espacio de trabajo. Guarda ahí los valores de desarrollo y staging, y deja fuera los de producción. La prueba es sencilla: si un valor sería un problema en una captura, no pertenece a un entorno compartido.
¿La documentación se actualiza si cambio una petición?
La parte generada viene de la colección, así que regenerar recoge el cambio. El texto que has escrito a mano se queda como lo escribiste, y por eso esa parte debe explicar por qué existe un endpoint en vez de repetir sus parámetros.
¿Exportar PDF o compartir enlace?
Un enlace, salvo que alguien necesite un archivo concreto. Un enlace compartido refleja la versión actual; un PDF es la foto de un momento y empieza a estar equivocado al día siguiente de enviarlo.
