insomnia documenter

Wie Postman Documenter, aber gegen Schlaflosigkeit! Mit diesem Tool können Sie mithilfe Ihrer Insomnia-Exportdatei wunderschöne API-Dokumentationsseiten erstellen.

Demo: https://insodoc.github.io/insomnia-documenter/
Tutorial und Demo-Video: https://www.youtube.com/watch?v=pq2u3FqVVy8

Inhaltsverzeichnis

• Inhaltsverzeichnis
• Anforderungen
• Erste Schritte
  • Verwenden von npx
  • Durch die globale Installation des Pakets
  • Optionen
  • Verwendung einer GitHub-Version
• Aktualisieren der API
• Benutzerdefinierte Stammpfade
• Lokales Ausführen der Seite
• Schlaflosigkeits-Plugin
• Änderungsprotokoll
• Beitrag
• Lizenz
• Insomnia Documenter für Unternehmen

Anforderungen

• Node.js (8.x oder höher wird empfohlen)
• Ein exportierter Insomnia-Arbeitsbereich JSON (v4)

Erste Schritte

Insomnia Documenter bietet ein CLI-Tool, mit dem Sie ganz einfach eine Dokumentationsseite einrichten können. Sie können es auf zwei Arten verwenden.

Verwenden von npx

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

Durch die globale Installation des Pakets

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

Optionen

 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

Verwendung einer GitHub-Version

Alternativ können Sie mit der Verwendung von Insomnia Documenter beginnen, indem Sie ein Release-Archiv von GitHub herunterladen und Ihre insomnia.json -Exportdatei zum Stammverzeichnis Ihrer Website hinzufügen.

Aktualisieren der API

Das Aktualisieren der API ist super einfach! Da Insomnia Documenter eine Plug-and-Play-Webanwendung ist, können Sie einfach Ihre insomnia.json durch Ihre neue exportierte JSON-Datei ersetzen. Stellen Sie einfach sicher, dass es insomnia.json heißt.

Das Gleiche gilt tatsächlich auch für das Logo ( logo.png ) und das Favicon ( favicon.ico ).

Benutzerdefinierte Stammpfade

Vielleicht möchten Sie mehrere APIs auf derselben Domäne dokumentieren? Vielleicht möchten Sie Ihre Dokumentationsseite auf GitHub-Seiten hosten? In diesem Fall (in vielen anderen Fällen) müssen Sie den Root-Pfad angeben. Dazu müssen Sie index.html öffnen und die folgende Zeile ersetzen:

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

mit so etwas:

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

In diesem Fall ruft die App die Datei insomnia.json aus dem Verzeichnis /path/to/docs ab. Dies gibt Ihnen mehr Flexibilität bei der Pflege Ihrer Dokumentationsseite (z. B. können Sie die Exportdatei an einem anderen Ort als dem Stammverzeichnis der Webseite speichern). Sie sollten KEINEN abschließenden Schrägstrich in die data-root einfügen.

Bitte beachten Sie, dass das Setzen dieses Attributs keine Auswirkungen auf das Favicon und das Logo der Seite hat. Sie werden weiterhin aus demselben Verzeichnis geladen, in dem sich index.html befindet.

Lokales Ausführen der Seite

Das Öffnen der Datei index.html schlägt in 99,9 % der Fälle fehl, da der Abruf genau so funktioniert. Um eine lokale Vorschau der Seite anzuzeigen, können Sie ein Tool wie zeit/serve verwenden:

npx serve

Die Seite wird unter http://localhost:5000 verfügbar sein.

Schlaflosigkeits-Plugin

devhammed hat ein fantastisches Insomnia-Plugin erstellt, mit dem Sie eine Dokumentationsseite direkt über die Benutzeroberfläche von Insomnia generieren können. Holen Sie sich das Plugin (npm – github)

Änderungsprotokoll

Bitte beachten Sie das Changelog-Dokument.

Beitrag

Das CLI-Tool ist ein Commander-Applet, während das Frontend selbst eine Svelte-App ist. Dieses Projekt befindet sich noch in der Beta-Phase, was bedeutet, dass es Fehler aufweist und hier und da verbessert werden kann. Ein Beitrag ist sehr willkommen :)

Klonen Sie das Repository:

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

Installieren Sie die Abhängigkeiten:

npm install

Kopieren Sie die Demo-Insomnia-Exportdatei:

cp docs/insomnia.json public/insomnia.json

Führen Sie einen Entwicklungs-Build mit Hot-Reload aus:

npm run dev

Erstellen Sie einen Produktions-Build:

npm run build

Fusseln:

npm run lint

Testen:

npm run test 

Lizenz

MIT.

Hinweis: Dieses Projekt steht in keiner Verbindung zu Kong und/oder Insomnia.

Insomnia Documenter für Unternehmen

Verfügbar als Teil des Tidelift-Abonnements

Die Betreuer von Insomnia Documenter und Tausenden anderer Pakete arbeiten mit Tidelift zusammen, um kommerziellen Support und Wartung für die Open-Source-Abhängigkeiten bereitzustellen, die Sie zum Erstellen Ihrer Anwendungen verwenden. Sparen Sie Zeit, reduzieren Sie Risiken und verbessern Sie den Zustand des Codes, während Sie gleichzeitig die Betreuer der genauen Abhängigkeiten bezahlen, die Sie verwenden. Erfahren Sie mehr.