Verwaltung der API-Dokumentation

Die API-Dokumentationsfunktion in Document360 macht es einfach, klare, interaktive Dokumentation zu erstellen, indem Sie Ihre API-Spezifikationsdateien hochladen. Dieser Prozess erstellt automatisch eine detaillierte Dokumentation, die alles von API-Endpunkten bis hin zu Methoden und Antworten abdeckt und Entwicklern hilft, Ihre API effektiver zu verstehen und zu nutzen.  

API-Dokumentation generieren

Es gibt drei Methoden, um API-Dokumentation in Document360 zu generieren:

• Von einer URL

• Aus einer JSON/YAML/YML-Datei

• Mit einem CI/CD-Fluss

HINWEIS

Document360 unterstützt OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1 und Postman API-Spezifikationen.

API-Dokumentation aus einer API-Spezifikationsdatei generieren

Um API-Referenzen aus einer API-Spezifikationsdatei (JSON/YAML/YML) zu erzeugen,

1. Navigiere zum gewünschten Projekt im Knowledge Base-Portal.

2. Wählen Sie die API-Dokumentation ({ }) in der linken Navigationsleiste aus.

3. Klicken Sie in der oberen Navigationsleiste auf das Dropdown-Menü "Erstellen " und wählen Sie Neue API. Dies zeigt das Referenzfenster für die neue API an.

4. Wählen Sie im Referenzfenster "Neue API" die Klick "API-Definition hochladen".

5. Klicken Sie auf entweder "Von meinem Gerät hochladen " oder " Vom Laufwerk auswählen ", um die Datei von Ihrem Gerät oder von Document360 Drive auszuwählen. Sie können Ihre Datei auch direkt in das Referenzfenster für neue APIs ziehen und absetzen.

HINWEIS

Der Importprozess der API-Dokumentation unterstützt Unterkategorien der zweiten Ebene mit dem > Symbol in OpenAPI-Tags (z. B. Pets > Details). Dies ermöglicht eine sauberere, verschachtelte Organisation der Endpunkte, bewahrt die Struktur während der Neusynchronisation und gewährleistet eine korrekte Anzeige und Navigation im linken Panel der API-Referenz.

Wenn Ihre hochgeladene Datei zugehörige Warnungen oder Warnungen enthält, können Sie diese ansehen, indem Sie die Dropdown-Menüs Warnungen und Warnungen erweitern, die im Referenzfenster für neue API erscheinen.

6. Klicken Sie auf Neue API-Referenz, um zum Veröffentlichungsbestätigungsfenster zu gelangen. Im Fenster sehen Sie eine Erfolgsmeldung sowie die Anzahl der erstellten Kategorien und Artikel.

7. Klicken Sie auf Veröffentlichen , um Ihre API-Dokumentation zu generieren.

HINWEIS

Um Ihre Dokumentation vor der Veröffentlichung einzusehen, klicken Sie auf Schließen , um zum Dokumentationsbildschirm zurückzukehren. Ihr Entwurf ist im Bereich Kategorien & Artikel sichtbar.

API-Dokumentation aus einer URL generieren

Um die API-Spezifikationsdatei als URL in Document360 hochzuladen,

1. Navigiere zum gewünschten Projekt im Knowledge Base-Portal.

2. Wählen Sie die API-Dokumentation ({ }) in der linken Navigationsleiste aus.

3. Klicken Sie in der oberen Navigationsleiste auf das Dropdown-Menü Erstellen , wählen Sie Neue API oder klicken Sie oben rechts auf die Schaltfläche Neue API . Dies zeigt das neue API-Referenzpanel an.

4. Im Quellcode-Bildschirm wählen Sie den Radio-Button "URL erstellen" aus und klicken Sie auf Nächst.

5. Im Bildschirm Quelleinstellungen geben Sie die URL Ihrer API-Spezifikationsdatei im URL-Feld ein.

6. Klicken Sie auf API-Referenz hinzufügen , um zum Finish-Bildschirm zu gelangen.

7. Auf dem Finish-Bildschirm können Sie die Anzahl der Kategorien und Artikel sehen, die für Ihre API-Spezifikationsdatei erstellt wurden.

8. Klicken Sie auf Veröffentlichen , um Ihre API-Dokumentation zu generieren.

API-Dokumentation mit einem CI/CD-Fluss generieren

Bevor Sie eine API-Spezifikationsdatei mit einem CI/CD-Flow hochladen, stellen Sie sicher, dass die neueste Version von Node.js auf Ihrem System installiert ist. Wenn Sie mit Node.js nicht vertraut sind, lesen Sie diese Anleitung für die Installationsanleitung.

Um die API-Spezifikationsdatei mit einem CI/CD-Flow hochzuladen,

1. Navigiere zum gewünschten Projekt im Knowledge Base-Portal.

2. Wählen Sie die API-Dokumentation ({ }) in der linken Navigationsleiste aus.

3. Klicken Sie in der oberen Navigationsleiste auf das Dropdown-Menü "Erstellen " und wählen Sie Neue API. Dies zeigt das Referenzfenster für die neue API an.

4. Im Bildschirm "Quell auswählen " wählen Sie die CI/CD-Flow-Funktaste aus.

5. Kopieren Sie den vollständigen CLI-Befehl, der aus dem Referenzfenster der neuen API angezeigt wird.

6. Im kopierten Befehl aktualisieren Sie den --path Wert mit:

   • Der vollständige Pfad zu deiner lokalen JSON/YAML/YML-Spezifikationsdatei. Zum Beispiel

     --path=/Users/yourname/projects/api/openapi.yaml

   • Eine gültige URL, die auf deine API-Spezifikationsdatei verweist. Zum Beispiel

     --path=https://example.com/api/openapi.yaml

7. Füge den aktualisierten Befehl in dein Terminal ein und drücke Enter.  

8. Deine API-Spezifikationsdatei wird hochgeladen und die API-Dokumentation wirdgeneriert.

HINWEIS

• Die erste Zeile (npm install d360 -g) installiert das CLI-Tool Document360. Du musst es nur beim ersten Mal spielen. Wenn es bereits installiert ist, kannst du diese Zeile überspringen.

• Wenn du den API-Schlüssel neu generierst, indem du auf das ()-Symbol in der Benutzeroberfläche klickst, musst du den --apiKey Wert in deinem CLI-Befehl aktualisieren, bevor du ihn erneut ausführen kannst. Der alte Schlüssel wird nicht mehr gültig sein.

Verwaltung von Webhooks (Events)

Wenn Ihre OpenAPI 3.1-Spezifikation Webhooks enthält, importiert Document360 diese und zeigt ein Ereignissymbol neben jedem Webhook an. Die Seite zeigt das Nutzlastschema und das Beispiel an. Wenn die Spezifikation kein Beispiel enthält, werden ein Standardbeispiel und eine Sample-Nutzlast angezeigt. Try It ist nicht für Webhooks verfügbar. Webhooks sind in Resync-Operationen enthalten, und Ihr benutzerdefinierter Inhalt wird nach der Regeneration behalten.

API-Dokumentation regenerieren

Wenn Sie Änderungen an Ihrer API vornehmen, wie zum Beispiel neue Endpunkte hinzufügen, müssen Sie Ihre API-Dokumentation in Document360 nicht manuell aktualisieren. Du kannst deine API-Dokumentation neu generieren, und Änderungen an deiner API werden automatisch in der aktualisierten Dokumentation angezeigt.

HINWEIS

Alle benutzerdefinierten Inhalte, die Sie Ihrer API-Dokumentation hinzufügen, werden behalten, wenn Sie Ihre API-Dokumentation neu generieren.

Generiere API-Dokumentation aus der URL neu

1. Navigiere zum gewünschten Projekt im Knowledge Base-Portal.

2. Wählen Sie die API-Dokumentation ({ }) in der linken Navigationsleiste aus.

3. Klicken Sie auf API-Referenzen im linken Navigationsverzeichnis.

4. Klicken Sie auf das More ()-Symbol neben der gewünschten API-Referenz, für die Sie die API-Dokumentation neu generieren möchten.

   1. Um API-Dokumentation aus der bestehenden URL zu regenerieren:

      • Klicke auf Resync.

      • Die API-Dokumentation wird gemäß der neuesten API-Spezifikationsdatei neu generiert.

   

   1. Um API-Dokumentation mit einer neuen URL neu zu generieren:

      • Klicken Sie auf Bearbeiten.

      • Geben Sie die neue URL im URL-Feld ein.

      • Klicken Sie auf Aktualisieren.

      • Die API-Dokumentation wird gemäß der API-Spezifikationsdatei auf der neuen URL neu generiert.

Generiere die API-Dokumentation aus einer API-Spezifikationsdatei neu

1. Navigiere zum gewünschten Projekt im Knowledge Base-Portal.

2. Wählen Sie die API-Dokumentation ({ }) in der linken Navigationsleiste aus.

3. Klicken Sie auf API-Referenzen im linken Navigationsverzeichnis.

4. Klicken Sie auf das More ()-Symbol neben der gewünschten API-Referenz, für die Sie die API-Dokumentation neu generieren möchten.

5. Klicken Sie Edit.

6. Laden Sie die neueste API-Spezifikationsdatei im JSON/YAML/YML-Format hoch.

7. Klicken Sie auf Aktualisieren. Die API-Dokumentation wird gemäß der neuesten API-Spezifikationsdatei neu generiert.

Regeneriere API-Dokumentation, integriert mit CI/CD-Fluss

Du kannst die API-Referenz in deinen CI/CD-Pipelines mit Hilfe deiner d360-npm-Pakete neu synchronisieren. D360 ist das Kommandozeilentool, das Ihnen hilft, Workflows einzurichten, die Ihre API-Dokumente mit Document360 synchronisieren.

Du kannst die Neusynchronisierung auch manuell mit dem untenstehenden Befehl ausführen.

d360 apidocs:resync 
                    --apiKey=API_key_value
                    --userId=user_id_value
                    --apiReferenceId=API_reference_value
                    --path=Spec_file_path

Verständnis der Endpunkt-Löschung während der Resynchronisierung

Wenn Sie Ihre API-Spezifikationsdatei aktualisieren, werden alle Endpunkte, die in der neuen Spezifikation nicht mehr vorhanden sind, dauerhaft gelöscht, ebenso wie alle benutzerdefinierten Inhalte, die auf diesen Endpunktseiten hinzugefügt wurden.

Um Ihre API-Spezifikationsdatei zu aktualisieren:

1. Laden Sie die aktualisierte API-Spezifikationsdatei in das Referenzfenster API-Bearbeiten hoch.

2. Wenn irgendwelche Endpunkte gelöscht werden, wird eine Warnung angezeigt. Klicken Sie auf Gelöschte Endpunkte anzeigen , um die Liste der betroffenen Endpunkte einzusehen.

3. Wählen Sie das Kontrollkästchen "Fortsetzen bestätigen" aus, um die Löschung zu bestätigen.

4. Klicken Sie auf Aktualisieren , um fortzufahren.

Gelöschte Endpunkte werden in den Papierkorb verschoben, wo sie bis zu 30 Tage vorschauig angezeigt werden können, aber nicht wiederhergestellt werden können.

 HINWEIS

Wenn Sie den Resync-API-Endpunkt programmatisch verwenden, senden ForceImport = false Sie Ihre Anfrage, um die Liste der gelöschten Endpunkte vorzusehen, ohne mit der Löschung fortzufahren. Senden ForceImport = true Sie zur Bestätigung und fahren Sie fort.

API-Quellcode herunterladen

HINWEIS

Um die API-Dateien herunterzuladen, stellen Sie sicher, dass in den Einstellungen des Knowledge Base-Portals der Quellcode zeigen der API eingeschaltet ist.

Hilfreiche Links