Wie erstelle ich eine API-Dokumentation in Postman?

how create api documentation postman

In diesem Tutorial wird erläutert, wie Sie mit minimalem Aufwand eine gut aussehende, gestaltete Dokumentation mithilfe der vom Postman Tool bereitgestellten API-Dokumentationsunterstützung erstellen:

Für jede interne oder öffentlich zugängliche API ist die Dokumentation einer der wichtigsten Bestandteile für ihren Erfolg.

Der Hauptgrund dafür ist, dass die Dokumentation die Art und Weise ist, wie Sie mit Ihren Benutzern kommunizieren.

• Wie soll Ihre API verwendet werden?
• Welche Statuscodes werden unterstützt?
• Was sind die Fehlercodes?
• Was sind alle Methodentypen verfügbar?

All diese Informationen sind erforderlich, damit jeder die API für den gewünschten Bedarf verwenden oder implementieren kann.

=> Sehen Sie sich hier die Simple Postman Training Series an.

Wie unterschiedlich ist c von c ++

Postman bietet eine benutzerfreundliche Dokumentationsmethode. Für die grundlegende Dokumentation müssen Sie lediglich auf eine Schaltfläche in der Postman-Sammlung klicken und eine öffentliche URL für Ihre API-Dokumentation abrufen.

Was du lernen wirst:

• API-Dokumentation in Postman erstellen
  • Dokumentationsfunktionen
  • Dokumentation erstellen
• Fazit
  • Literatur-Empfehlungen

API-Dokumentation in Postman erstellen

Dokumentationsfunktionen

Zu den herausragenden Funktionen des Postman-Dokumentationsgenerators gehören:

• Es unterstützt die Markdown-Syntax. Markdown ist eine generische Dokumentationssyntax, die Sie normalerweise bei jedem Github-Projekt beachten sollten. Dadurch können Sie das Styling und die Textformatierung vertrauter und einfacher gestalten.
• Keine spezifischen Syntax / Anforderungen zum Erstellen der Dokumentation. Die Anforderungs- und Sammlungsinformationen werden am besten verwendet, um Dokumentation zu generieren.
• Es kann unter einer öffentlichen URL oder in einer benutzerdefinierten Domain (für Unternehmensbenutzer) veröffentlicht werden.
• Generiert Codefragmente zum Aufrufen der API in verschiedenen Sprachen wie C #, PHP, Ruby, Python, Node usw.

Dokumentation erstellen

Der Postman-Dokumentgenerator bezieht sich auf die Beschreibung der Sammlung, des Ordners und der einzelnen Anforderungen und sortiert diese beim Erstellen oder Generieren der Dokumentation für die Sammlung.

Es verwendet verschiedene Anforderungsparameter wie Header, Abfragezeichenfolgenparameter und Formularparameter und gibt die Verwendung dieser Werte in der Anforderungsdokumentation an.

Hier ist ein Video-Tutorial:

Erstellen wir eine Basissammlung mit 3 Anforderungen unter Verwendung derselben Test-API wie in unseren anderen Artikeln. Wir werden einige Informationen zur Sammlungsbeschreibung sowie zu den einzelnen Anforderungen hinzufügen und einige Beispielanforderungen und -antworten erstellen, die auch beim Erstellen der Dokumentation erfasst werden.

Führen Sie die folgenden Schritte aus, um grundlegende Informationen zu den Anforderungen hinzuzufügen und anschließend die Dokumentation zu erstellen.

# 1) Erstellen Sie eine Sammlung mit 3 Anforderungen, d. H. Benutzer registrieren, Benutzer anmelden und Benutzer abrufen (siehe Hier für Anforderungsnutzdaten und API-URLs).

#zwei) Fügen wir nun der Sammlung einige Informationen im Markdown-Format hinzu. Markdown ist ein Standardformat, das für fast alle Dokumentationen in Github verwendet wird (Weitere Informationen zu Markdown finden Sie unter Hier ).

Wir werden der Sammlungsbeschreibung einige Informationen im folgenden Markdown-Format hinzufügen.

Eine Vorschau des Markdowns finden Sie im Open-Source-Webportal Hier.

#3) Jetzt werden wir die Beschreibungen zu einzelnen Anfragen in der Sammlung hinzufügen. Ähnlich wie bei der Sammlung wird das Markdown-Format auch für Anforderungsbeschreibungen unterstützt (Ausführlichere Informationen zum Markdown-Handbuch finden Sie unter Hier ).

Sehen wir uns ein Beispiel für eine der Anforderungen für den Endpunkt 'Benutzer registrieren' an (dasselbe kann auch auf andere Anforderungen angewendet werden).

Markdown-Text:

Markdown-Vorschau:

# 4) Lassen Sie uns für alle API-Endpunkte ein Beispiel erfassen oder speichern, das vom Dokumentationsgenerator verwendet wird.

Ein Beispiel ist nichts anderes als eine Beispielanforderungsantwort für die API-Anforderung. Durch Speichern der Antwort als Beispiel kann der Dokumentationsgenerator sie als Teil der Dokumentation selbst erfassen.

Um ein Beispiel zu speichern, drücken Sie die Taste 'Senden' Klicken Sie auf die Schaltfläche, um die Anforderung auszuführen, und klicken Sie auf der Registerkarte Antwort auf Antwort speichern -> Als Beispiel speichern .

Sobald das Beispiel gespeichert ist, bleibt es in der Sammlung erhalten und kann in Zukunft jederzeit über eine aufgerufen werden Beispiele Link im Request Builder.

# 5) Nachdem alle oben genannten Informationen hinzugefügt wurden, sehen wir uns an, wie Sie eine Dokumentationsvorschau erstellen.

Öffnen Sie die Sammlungsoptionen und klicken Sie auf „ Dokumente veröffentlichen ”.

Hinweis: Hierbei ist zu beachten, dass nur registrierte Benutzer mit Postman die Funktion zum Veröffentlichen von Dokumenten auf Postman verwenden können. Die Registrierung ist kostenlos, muss jedoch über Ihr E-Mail-Konto erfolgen. Es gibt andere Funktionen, wie das Freigeben von Sammlungen und Arbeitsbereichen, das Erstellen von Monitoren usw., die den registrierten Konten hinzugefügt werden.

# 6) Einmal ' Dokumente veröffentlichen Wird ausgeführt, wird eine Browser-Registerkarte mit den Details der Postman-Sammlung geöffnet (intern hostet Postman diese Sammlung zusätzlich zum lokalen Dateisystem des Benutzers auch auf seinen eigenen Servern).

Klicke auf 'Vorschau' um die Dokumentation anzuzeigen, bevor sie veröffentlicht wird.

'' Sammlung veröffentlichen Der Link veröffentlicht die Dokumentation unter einer öffentlich zugänglichen URL. Es wird im Allgemeinen nicht empfohlen, APIs mit vertraulichen Berechtigungsinformationen zu veröffentlichen, um sie unter der öffentlichen URL zu veröffentlichen. Solche APIs können mithilfe benutzerdefinierter Domänen mit Unternehmenskonten des Postboten veröffentlicht werden.

# 7) Mal sehen, wie die Dokumentationsvorschau aussieht. Klicken Sie auf „ Vorschau der Dokumentation ”Öffnet die Dokumentation in einem Vorschaumodus, der auf den Postman-Servern gehostet wird. Lassen Sie uns sehen, welche unterschiedlichen Details in der Dokumentation erfasst werden (wie wir sie an verschiedenen Stellen konfiguriert haben). Zum Beispiel , Sammlungsbeschreibung, Anforderungsbeschreibung & Beispiele).

In den obigen 2 Screenshots können Sie sehen, dass alle Informationen, die der Sammlung und den Anforderungsbeschreibungen hinzugefügt wurden, in der Dokumentationsvorschau in einer Art Abschriften erfasst werden.

So öffnen Sie eine .bin-Datei in Windows

Außerdem enthält die Dokumentation standardmäßig hervorgehobene Sprachbindungen, was es für jemanden, der die API-Anforderung direkt in der aufgelisteten Sprache stellen möchte, viel einfacher macht.

# 8) Sie können damit auch sehr grundlegende Stiländerungen vornehmen, z. B. die Hintergrundfarbe ändern, die Hintergrund- und Vordergrundfarbe der Header-Vorlagen ändern usw. Insgesamt reicht die Standardansicht jedoch aus, um eine wirklich gute Dokumentation zu veröffentlichen, die viele davon erfasst wichtige Details zur API.

Fazit

In diesem Tutorial haben wir uns mit der API-Dokumentationsunterstützung von Postman befasst, mit der wir mit minimalem Aufwand eine gut aussehende, gestaltete Dokumentation erstellen können.

Es ermöglicht auch viele gute Vorlagen und benutzerdefinierte Stile, die auf die generierten Dokumente angewendet werden können, und ermöglicht das Veröffentlichen von Dokumentation unter einer öffentlichen URL.

Für private API-Endpunkte ist auch vorgesehen, Dokumentation in einer benutzerdefinierten Domäne zu veröffentlichen, die für Unternehmenskonten oder Benutzer konfiguriert werden kann.

Weiterführende Literatur = >> So veröffentlichen Sie Pact Contract to Pact Broker

=> Besuchen Sie hier, um Postman From Scratch zu lernen.

Literatur-Empfehlungen

• POSTMAN Tutorial: API-Tests mit POSTMAN
• Wie und wann werden Postman Pre-Request- und Post Request-Skripte verwendet?
• Wie verwende ich Postman zum Testen verschiedener API-Formate?
• Wie verwende ich die Befehlszeilenintegration mit Newman in Postman?
• Rest API Tutorial: REST API Architektur und Einschränkungen
• Generieren Sie eine lebende Dokumentation mit Pickles für Specflow-Feature-Dateien
• Automatisieren der Antwortvalidierung mit Zusicherungen in Postman
• Rest-API-Antwortcodes und Arten von Rest-Anforderungen