En este post mostraré como realizar la documentación de un API/REST con el uso de Insomnia.
Para empezar vamos a descargar Insomnia Core (para hacer los requests) e Insomnia Designer (para testing y trabajar de manera colaborativa)
Paso 1: En Insomnia Core, creamos un nuevo Workspace (una forma de separar proyectos en Insomnia , en mi caso lo llamaré ‘Mini-API’ )
Paso 2: Crear un nuevo Entorno o Enviroment (esto nos permitirá tener separado los datos de «Producción» y «Pruebas»). Para hacerlo debemos hacer ‘Ctrl+E’ y luego pulsar en ‘+’. En mi caso solo crearé Pruebas.
Paso 3: Una vez creado el entorno de Pruebas, procedemos a agregar las variables de entorno, en mi caso el ‘baseUrl’ (Url de mi servidor de pruebas) que lo usaré para los requests.
Paso 4: Crear los requests o consultas al API/REST. Para hacerlo debemos hacer ‘Ctrl+N’. En el ejemplo de la imagen podemos apreciar a un POST y su resultado:
Paso 5: Una vez que hemos terminado de probar nuestra API/REST, vamos a exportarlo en un archivo json. En mi caso lo he llamado «doc.json»
Paso 6: Antes de realizar este paso debemos asegurarnos de tener instalado nodeJS y npx. Nos posicionamos desde consola en la carpeta donde se encuentra nuestro archivo, y escribimos
npx insomnia-documenter --config doc.json
Ahora tendremos generada toda la documentación!
Paso 7: Para ver la documentación podemos hacerlo con serve
npx serve
Paso 8 (opcional): Es posible que necesitemos subir el contenido a una carpeta de nuetro servidor y nos encontremos con el siguiente error:
Para este caso recomiendo modificar la línea 15 del index.html, de tal manera que en ‘data-root’ indiquemos la carpeta en la que se encuentra la documentación:
<div id="app" data-root="/docs"></div>Y por fin con eso ya tendremos nuestra documentación!
PD: Si necesitamos actualizar la documentación solo debemos cambiar el archivo json y nada más.
/r/Geeks by @jRodrigoPuca 