insomnia documenter

Comme Postman Documenter mais pour Insomnia ! Avec cet outil, vous pouvez générer de belles pages de documentation API à l'aide de votre fichier d'exportation Insomnia.

Démo : https://insodoc.github.io/insomnia-documenter/
Tutoriel et vidéo de démonstration : https://www.youtube.com/watch?v=pq2u3FqVVy8

Table des matières

• Table des matières
• Exigences
• Commencer
  • Utiliser npx
  • En installant le package globalement
  • Possibilités
  • Utiliser une version de GitHub
• Mise à jour de l'API
• Chemins racine personnalisés
• Exécuter la page localement
• Plugin Insomnie
• Journal des modifications
• Contribution
• Licence
• Documentateur d'insomnie pour les entreprises

Exigences

• Node.js (8.x ou supérieur recommandé)
• Un espace de travail Insomnia exporté JSON (v4)

Commencer

Insomnia Documenter propose un outil CLI pour faciliter la configuration d'une page de documentation. Vous pouvez l'utiliser de deux manières.

Utiliser npx

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

En installant le package globalement

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

Possibilités

 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

Utiliser une version de GitHub

Vous pouvez également commencer à utiliser Insomnia Documenter en téléchargeant une archive de version depuis GitHub et en ajoutant votre fichier d'exportation insomnia.json au répertoire racine de votre site.

Mise à jour de l'API

Mettre à jour l'API est super simple ! Étant donné qu'Insomnia Documenter est une application Web plug-and-play, vous pouvez simplement remplacer votre insomnia.json par votre nouveau fichier JSON exporté. Assurez-vous simplement qu'il s'appelle insomnia.json .

La même chose s'applique également au logo ( logo.png ) et au favicon ( favicon.ico ).

Chemins racine personnalisés

Peut-être souhaitez-vous documenter plusieurs API sur le même domaine ? Peut-être souhaitez-vous héberger votre page de documentation sur les pages GitHub ? Dans ce cas (dans de nombreux autres cas), vous devrez spécifier quel est le chemin racine. Pour ce faire, vous devez ouvrir index.html et remplacer la ligne suivante :

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

avec quelque chose comme ça :

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

Dans ce cas, l'application récupérera le fichier insomnia.json dans le répertoire /path/to/docs . Cela vous donne plus de flexibilité sur la manière dont vous souhaitez gérer votre page de documentation (par exemple, vous pouvez stocker le fichier d'exportation ailleurs que dans le répertoire racine de la page Web). Vous ne devez PAS mettre de barre oblique finale dans la propriété data-root .

Veuillez noter que la définition de cet attribut n'affectera pas le favicon et le logo de la page. Ils seront toujours chargés à partir du même répertoire où se trouve index.html .

Exécuter la page localement

L'ouverture du fichier index.html échouera à se charger dans 99,9 % des cas, car c'est ainsi que fonctionne la récupération. Pour prévisualiser la page localement, vous souhaiterez peut-être utiliser un outil tel que zeit/serve :

npx serve

La page sera disponible sur http://localhost:5000.

Plugin Insomnie

devhammed a créé un superbe plugin Insomnia qui vous permet de générer une page de documentation directement depuis l'interface d'Insomnia. Obtenez le plugin (npm - github)

Journal des modifications

Veuillez consulter le document Changelog.

Contribution

L'outil CLI est une applet de commande, tandis que le frontend lui-même est une application Svelte. Ce projet est encore en version bêta, ce qui signifie qu'il comporte des bugs et peut être amélioré ici et là. La contribution est la bienvenue :)

Clonez le dépôt :

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

Installez les dépendances :

npm install

Copiez le fichier d'exportation de la démo Insomnia :

cp docs/insomnia.json public/insomnia.json

Exécutez une version de développement avec rechargement à chaud :

npm run dev

Créez une version de production :

npm run build

Pelucheux :

npm run lint

Essai:

npm run test 

Licence

MIT.

Remarque : ce projet n'est pas affilié à Kong et/ou Insomnia.

Documentateur d'insomnie pour les entreprises

Disponible dans le cadre de l’abonnement Tidelift

Les responsables d'Insomnia Documenter et de milliers d'autres packages travaillent avec Tidelift pour fournir un support commercial et une maintenance pour les dépendances open source que vous utilisez pour créer vos applications. Gagnez du temps, réduisez les risques et améliorez la santé du code, tout en rémunérant les responsables des dépendances exactes que vous utilisez. Apprendre encore plus.