insomnia documenter

¡Como Postman Documenter pero para Insomnia! Con esta herramienta puedes generar hermosas páginas de documentación API usando tu archivo de exportación de Insomnia.

Demostración: https://insodoc.github.io/insomnia-documenter/
Vídeo tutorial y demostración: https://www.youtube.com/watch?v=pq2u3FqVVy8

Tabla de contenido

• Tabla de contenido
• Requisitos
• Empezando
  • Usando npx
  • Instalando el paquete globalmente
  • Opciones
  • Usando una versión de GitHub
• Actualizando la API
• Rutas raíz personalizadas
• Ejecutar la página localmente
• Complemento de insomnio
• Registro de cambios
• Contribución
• Licencia
• Documentador de insomnio para empresas

Requisitos

• Node.js (se recomienda 8.x o superior)
• Un JSON del espacio de trabajo de Insomnia exportado (v4)

Empezando

Insomnia Documenter ofrece una herramienta CLI para que sea muy fácil configurar una página de documentación. Puedes usarlo de dos maneras.

Usando npx

npx insomnia-documenter --config /path/to/insomnia/config.json

Instalando el paquete globalmente

npm i -g insomnia-documenter
insomnia-documenter --config /path/to/insomnia/config.json

Opciones

 Options:
  -c, --config <location>  Location of the exported Insomnia JSON config.
  -l, --logo <location>    Project logo location (48x48px PNG).
  -f, --favicon <location>    Project favicon location (ICO).
  -o, --output <location>  Where to save the file (defaults to current working directory).
  -h, --help               output usage information

Usando una versión de GitHub

Alternativamente, puede comenzar a usar Insomnia Documenter descargando un archivo de versión de GitHub y agregando su archivo de exportación insomnia.json al directorio raíz de su sitio.

Actualizando la API

¡Actualizar la API es súper simple! Dado que Insomnia Documenter es una aplicación web plug-and-play, puede simplemente reemplazar su insomnia.json con su nuevo archivo JSON exportado. Solo asegúrate de que se llame insomnia.json .

Lo mismo se aplica también al logotipo ( logo.png ) y al favicon ( favicon.ico ).

Rutas raíz personalizadas

¿Quizás quieras documentar varias API en el mismo dominio? ¿Quizás quieras alojar tu página de documentación en páginas de GitHub? En este (y en muchos otros casos), deberá especificar cuál es la ruta raíz. Para hacer esto, debes abrir index.html y reemplazar la siguiente línea:

 < div id =" app " > </ div >

con algo como esto:

 < div id =" app " data-root =" /path/to/docs " > </ div >

En este caso, la aplicación recogerá el archivo insomnia.json del directorio /path/to/docs . Esto le brinda más flexibilidad sobre cómo desea mantener su página de documentación (por ejemplo, puede almacenar el archivo de exportación en otro lugar que no sea el directorio raíz de la página web). NO debe colocar una barra diagonal en la propiedad data-root .

Tenga en cuenta que configurar este atributo no afectará el favicon ni el logotipo de la página. Aún se cargarán desde el mismo directorio donde está index.html .

Ejecutar la página localmente

Al abrir el archivo index.html no se cargará en el 99,9% de los casos porque así es como funciona la recuperación. Para obtener una vista previa de la página localmente, es posible que desee utilizar una herramienta como zeit/serve:

npx serve

La página estará disponible en http://localhost:5000.

Complemento de insomnio

devhammed ha creado un increíble complemento de Insomnia que le permite generar una página de documentación directamente desde la interfaz de Insomnia. Obtenga el complemento (npm - github)

Registro de cambios

Consulte el documento de registro de cambios.

Contribución

La herramienta CLI es un subprograma comandante, mientras que la interfaz en sí es una aplicación Svelte. Este proyecto todavía está en versión beta, lo que significa que tiene errores y se puede mejorar aquí y allá. La contribución es bienvenida :)

Clonar el repositorio:

git clone [email protected]:jozsefsallai/insomnia-documenter.git
cd insomnia-documenter

Instale las dependencias:

npm install

Copie el archivo de exportación de demostración de Insomnia:

cp docs/insomnia.json public/insomnia.json

Ejecute una compilación de desarrollo con recarga en caliente:

npm run dev

Cree una compilación de producción:

npm run build

Pelusa:

npm run lint

Pruebas:

npm run test 

Licencia

MIT.

Nota: este proyecto no está afiliado a Kong y/o Insomnia.

Documentador de insomnio para empresas

Disponible como parte de la suscripción Tidelift

Los mantenedores de Insomnia Documenter y miles de otros paquetes están trabajando con Tidelift para brindar soporte comercial y mantenimiento para las dependencias de código abierto que utiliza para crear sus aplicaciones. Ahorre tiempo, reduzca el riesgo y mejore la salud del código, mientras paga a los mantenedores de las dependencias exactas que utiliza. Obtenga más información.