Verwalten der API-Dokumentation

Pläne zur Unterstützung API Dokumentation

Mit der API-Dokumentationsfunktion in Document360 können Sie ganz einfach klare, interaktive Dokumentationen erstellen, indem Sie Ihre API-Spezifikationsdateien hochladen. Bei diesem Prozess wird automatisch eine detaillierte Dokumentation erstellt, die alles abdeckt, von API-Endpunkten bis hin zu Methoden und Antworten, und Entwicklern hilft, Ihre API besser zu verstehen und zu nutzen.

Generieren der API-Dokumentation

Es gibt drei Methoden zum Generieren von API-Dokumentation in Document360:

• Von einer URL

• Aus einer JSON/YAML-Datei

• Mit einem CI/CD-Fluss

ANMERKUNG

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

Generieren von API-Dokumentation aus einer API-Spezifikationsdatei

So generieren Sie API-Verweise aus einer API-Spezifikationsdatei (JSON/YAML/YML):

1. Navigieren Sie im Wissensdatenbank-Portal zum gewünschten Projekt.

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

3. Klicken Sie in der oberen Navigationsleiste auf das Dropdown-Menü Erstellen und wählen Sie Neue API aus. Daraufhin wird das Fenster Neue API-Referenz angezeigt.

4. Wählen Sie die Option API-Definition hochladen im Fenster Neue API-Referenz aus.

5. Klicken Sie entweder auf Von meinem Gerät hochladen oder Auf Aus Drive auswählen , um die Datei von Ihrem Gerät bzw. Document360 Drive auszuwählen. Sie können Ihre Datei auch direkt per Drag & Drop in das Referenzfenster Neue API ziehen.

Wenn Ihrer hochgeladenen Datei Warnungen oder Warnungen zugeordnet sind, können Sie diese anzeigen, indem Sie die Dropdown-Menüs "Warnungen " und "Warnungen" erweitern, die im Referenzfenster "Neue API" angezeigt werden.

6. Klicken Sie auf Neue API-Referenz , um zum Bestätigungsfenster für die Veröffentlichung zu navigieren. In dem Fenster wird eine Erfolgsmeldung angezeigt, zusammen mit der Anzahl der erstellten Kategorien und Beiträge.

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

ANMERKUNG

Um Ihre Dokumentation vor der Veröffentlichung zu überprüfen, klicken Sie auf Schließen , um zum Bildschirm Dokumentation zurückzukehren. Ihr Entwurf wird im Bereich "Kategorien & Artikel" angezeigt.

Generieren von API-Dokumentation aus einer URL

Um die API-Spezifikationsdatei als URL in Document360 hochzuladen,

1. Navigieren Sie im Wissensdatenbank-Portal zum gewünschten Projekt.

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

3. Klicken Sie in der oberen Navigationsleiste auf das Dropdown-Menü Erstellen und wählen Sie Neue API aus, oder klicken Sie auf die Schaltfläche Neue API in der oberen rechten Ecke. Daraufhin wird der Bereich Neue API-Referenz angezeigt.

4. Wählen Sie im Bildschirm Quelle auswählen das Optionsfeld Aus URL erstellen aus, und klicken Sie auf Weiter.

5. Geben Sie im Bildschirm Quelleinstellungen die URL für Ihre API-Spezifikationsdatei in das URL-Feld ein.

6. Klicken Sie auf API-Referenz hinzufügen , um zum Bildschirm Fertig stellen zu navigieren.

7. Auf dem Bildschirm Fertig stellen sehen Sie die Anzahl der Kategorien und Artikel, die für Ihre API-Spezifikationsdatei erstellt wurden.

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

ANMERKUNG

Wenn Sie Ihre API-Dokumentation vor der Veröffentlichung überprüfen möchten, klicken Sie auf dem Bildschirm "Fertigstellen" auf "Schließen ", um zum Bildschirm "Dokumentation" zurückzukehren. Sie können die Entwürfe Ihrer API-Dokumentation im Bereich "Kategorien und Artikel" sehen.

Generieren von API-Dokumentation mit einem CI/CD-Ablauf

Bevor Sie eine API-Spezifikationsdatei mit einem CI/CD-Ablauf hochladen, stellen Sie sicher, dass die neueste Version von Node.js auf Ihrem System installiert ist. Wenn Sie mit Node.js nicht vertraut sind, finden Sie unter this guide Installationsanweisungen.

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

1. Navigieren Sie im Wissensdatenbank-Portal zum gewünschten Projekt.

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

3. Klicken Sie in der oberen Navigationsleiste auf das Dropdown-Menü Erstellen und wählen Sie Neue API aus. Daraufhin wird das Popup-Fenster Neue API-Referenz angezeigt.

4. Wählen Sie im Bildschirm Quelle auswählen das Optionsfeld CI/CD-Fluss aus und klicken Sie auf Weiter.

5. Kopieren Sie den vollständigen CLI-Befehl, der aus dem Popup-Fenster Neue API-Referenz angezeigt wird.

6. Aktualisieren Sie im kopierten Befehl den --path Wert mit:

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

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

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

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

7. Fügen Sie den aktualisierten Befehl in Ihr Terminal ein und drücken Sie die Eingabetaste.  

8. Ihre API-Spezifikationsdatei wird hochgeladen und die API-Dokumentationwird generiert.

ANMERKUNG

• In der ersten Zeile (npm install d360 -g) wird das CLI-Tool Document360 installiert. Sie müssen es nur beim ersten Mal ausführen. Wenn es bereits installiert ist, können Sie diese Zeile überspringen.

• Wenn Sie den API-Schlüssel neu generieren, indem Sie auf das Symbol () in der Benutzeroberfläche klicken, müssen Sie den --apiKey Wert in Ihrem CLI-Befehl aktualisieren, bevor Sie ihn erneut ausführen. Der alte Schlüssel ist nicht mehr gültig.

API-Dokumentation zum erneuten Generieren

Wenn Sie Änderungen an Ihrer API vornehmen, z. B. Endpunkte hinzufügen, müssen Sie Ihre API-Dokumentation in Document360 nicht manuell aktualisieren. Sie können Ihre API-Dokumentation einfach neu generieren, und alle Änderungen an Ihrer API werden automatisch in der API-Dokumentation widergespiegelt.

ANMERKUNG

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

Erneutes Generieren der API-Dokumentation aus der URL

1. Navigieren Sie im Wissensdatenbank-Portal zum gewünschten Projekt.

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

3. Klicken Sie im linken Navigationslistenbereich auf API-Dokumentreferenz .

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

   1. So generieren Sie die API-Dokumentation aus der vorhandenen URL neu:

      • Klicken Sie auf Erneut synchronisieren.

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

   2. So generieren Sie die API-Dokumentation mit einer neuen URL neu:

      • Klicken Sie auf Bearbeiten.

      • Geben Sie die neue URL in das Feld URL ein.

      • Klicken Sie auf Aktualisieren.

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

Erneutes Generieren der API-Dokumentation aus einer API-Spezifikationsdatei

1. Navigieren Sie im Wissensdatenbank-Portal zum gewünschten Projekt.

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

3. Klicken Sie im linken Navigationslistenbereich auf API-Dokumentreferenz .

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

5. Klicken Sie auf Edit.

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

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

Regenerieren der API-Dokumentation, die in den CI/CD-Fluss integriert ist

Sie können die API-Referenz in Ihren CI/CD-Pipelines mit Hilfe Ihrer d360 npm-Pakete neu synchronisieren. D360 ist das Befehlszeilentool, mit dem Sie Workflows einrichten können, die Ihre API-Dokumente mit Document360 synchronisieren.

Sie können die Neusynchronisierung auch manuell mit dem folgenden Befehl durchführen.

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

API-Referenz herunterladen

ANMERKUNG

Um die API-Dateien herunterzuladen, stellen Sie sicher, dass der Schalter Download-API-Referenz anzeigen in den Einstellungen des Wissensdatenbank-Portals aktiviert ist.

Fehlerbehebung

Fehlende oder falsche Server-URL in OpenAPI

Fehler: Dieser Fehler tritt auf, wenn die Server-URL in der OpenAPI-Spezifikation fehlt oder falsch konfiguriert ist. Infolgedessen wissen API-Benutzer nicht, wohin sie API-Anfragen senden sollen, und die Schaltfläche "Ausprobieren" ist in der API-Dokumentation möglicherweise nicht verfügbar. Die Ursache ist in der Regel ein fehlender oder falscher servers Abschnitt in der OpenAPI-Spezifikation.

Schritte zur Behebung

Um dieses Problem zu beheben, stellen Sie sicher, dass die OpenAPI-Spezifikation die richtige Server-URL enthält:

1. Definieren Sie die Server-URL in der OpenAPI-Spezifikation:

   servers:
     - url: https://apihub.document360.io
       description: Main API hub

2. Definieren Sie für regionsbasierte APIs mehrere Server-URLs:

   servers:
     - url: https://apihub.document360.io
       description: Global API hub
     - url: https://apihub.us.document360.io
       description: US region API hub

3. Stellen Sie sicher, dass alle API-Clients (Postman, cURL usw.) die richtige Server-URL verwenden, wenn sie Anforderungen stellen.

ANMERKUNG

Die oben genannten URLs sind Beispiele. Die richtige Server-URL finden Sie in Ihrer spezifischen API-Konfiguration.

Beispiel:

YAML-Beispiel für fehlend servers Abschnitt:

paths:
  /users:
    get:
      summary: Retrieve a list of users
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    userId:
                      type: integer
                    userName:
                      type: string

Um dieses Problem zu vermeiden, stellen Sie sicher, dass die servers -Abschnitt ist in der OpenAPI-Spezifikation ordnungsgemäß definiert, um zu verhindern, dass API-Verbraucher API-Anforderungs-URLs manuell erstellen müssen.

401 nicht autorisierter Fehler durch falsche Server-URL

Fehler: Dieser Fehler tritt auf, wenn API-Anforderungen eine nicht autorisierte 401-Antwort zurückgeben. Dies geschieht in der Regel, wenn die falsche Server-URL in API-Anforderungen verwendet wird. Wenn Sie https://apihub.document360.io z. B. anstelle von verwenden,https://apihub.us.document360.io führt dies zu Authentifizierungsfehlern.

Schritte zur Behebung:

Um dieses Problem zu beheben, führen Sie die folgenden Schritte aus, um die korrekte Verwendung der Server-URL und die ordnungsgemäße Authentifizierung sicherzustellen:

1. Stellen Sie sicher, dass API-Anforderungen den richtigen regionsbasierten Endpunkt verwenden.

2. Vergewissern Sie sich, dass die richtige Client-ID und der richtige geheime Clientschlüssel verwendet werden.

Beispiel für eine korrekte API-Anfrage:

GET https://apihub.us.document360.io/v2/Articles/{article_id}/en?appendSASToken=true

ANMERKUNG

Die obige URL ist ein Beispiel. Die richtige Server-URL finden Sie in Ihrer spezifischen API-Konfiguration.

3. Stellen Sie sicher, dass das Authentifizierungstoken korrekt in den Anforderungsheadern enthalten ist.

Fehlende Server-URL in der API-Dokumentation

Fehler: Dieses Problem tritt auf, wenn API-Consumer nicht sicher sind , welche Basis-URL sie für ihre Anfragen verwenden sollen. Dies geschieht in der Regel, wenn die Server-URL in der Dokumentation nicht eindeutig angegeben ist, obwohl sie in der OpenAPI-Spezifikation möglicherweise korrekt konfiguriert ist.

Schritte zur Behebung:

Um Verwirrung zu vermeiden und sicherzustellen, dass API-Verbraucher die richtige Basis-URL kennen:

1. Geben Sie die Basis-URL explizit in der API-Dokumentation an.

Beispiele:

Vergleichstabelle: Server-URL vorhanden vs. fehlende

ANMERKUNG

Die oben genannten URLs sind Beispiele. Die richtige Server-URL finden Sie in Ihrer spezifischen API-Konfiguration.

Um dieses Problem zu vermeiden, stellen Sie sicher, dass die Server-URL in der API-Dokumentation eindeutig angegeben ist, um Verwirrung zu vermeiden.

403-Fehler bei Verwendung der Funktion "Ausprobieren" mit einer OAS-Datei

Fehler:

Nach dem erfolgreichen Hochladen einer OAS-Datei führt ein Klick auf die Funktion Ausprobieren zu einem 403-Fehler. Dieser Fehler tritt auf, wenn in der OAS-Datei eine Definition für den BearerAuth-Sicherheitsmechanismus fehlt.

Schritte zur Behebung:

Gehen Sie folgendermaßen vor, um den Fehler 403 zu beheben:

1. Überprüfen Sie, ob die BearerAuth-Sicherheitsdefinition in Ihrer OAS-Datei vorhanden ist.

2. Wenn die BearerAuth-Definition fehlt, fügen Sie die BearerAuth-Sicherheitsdefinition in die OAS-Datei ein und laden Sie sie erneut hoch.

3. Überprüfen Sie während des Importvorgangs, ob Warnungen im Zusammenhang mit der Bearerauthentifizierung ausgelöst werden, und beheben Sie diese entsprechend.

Falsches HTML-Styling in der API-Antwort

Beim Abrufen des HTML-Inhalts eines Artikels über eine API wird die Antwort in JSON formatiert, das Escapeing (\") verwendet, um bestimmte Zeichen sicher zu verarbeiten. Durch diese Maskierung werden Zeichen wie Anführungszeichen, umgekehrte Schrägstriche und Zeilenumbrüche geändert, um Datenübertragungsfehler zu vermeiden. Wenn die maskierten Zeichen jedoch nicht zurückkonvertiert werden (ohne Escape), kann die HTML-Struktur beschädigt werden, was beim Rendern zu Stilproblemen führt.

Zum Beispiel ein einfacher HTML-Absatz:

<p>This is a "sample" paragraph.</p>

Kann in der JSON-Antwort wie folgt angezeigt werden:

"<p>This is a \"sample\" paragraph.</p>"

Die mit Escapezeichen versehenen doppelten Anführungszeichen (\") stellen sicher, dass der JSON-Code gültig bleibt, aber wenn er nicht maskiert ist, wird der HTML-Code möglicherweise nicht korrekt gerendert.

Schritte zur Behebung

1. Rufen Sie den HTML-Inhalt über die API ab und überprüfen Sie die Antwort.

2. Suchen Sie in der JSON-Antwort nach maskierten Zeichen, z. B.:

   • \" (maskierte doppelte Anführungszeichen)

   • \\ (Escape-Backslashes)

   • \n (Zeilenumbruch)

   • \t (Registerkarte)

3. Heben Sie die Maskierung des JSON-Inhalts auf, bevor Sie ihn rendern. Dadurch wird die ursprüngliche HTML-Struktur wiederhergestellt.

4. Überprüfen Sie die Formatierung nach dem Aufheben der Maskierung, um sicherzustellen, dass der Inhalt korrekt angezeigt wird.

5. Wenn das Problem weiterhin besteht, überprüfen Sie, ob zusätzliche Änderungen in Ihrem Code die API-Antwort ändern.

   

   Sobald die Maskierung ordnungsgemäß aufgehoben ist, wird der HTML-Code wie erwartet angezeigt, wodurch Stildiskrepanzen vermieden werden.

Variablen und Snippets werden in der API-Antwort nicht gerendert

Beim Abrufen von Artikelinhalten {{variable.UserName}} über die API können Variablen und Snippets unverarbeitet erscheinen (z. B. anstelle von tatsächlichen Werten). Dies geschieht in der Regel, wenn der "isForDisplay" Parameter nicht korrekt eingestellt ist.

• Wenn "isForDisplay" = true, gibt die API den Artikelinhalt zurück, wobei alle Variablen und Snippets vollständig gerendert sind. Das bedeutet, dass die Platzhalter durch tatsächliche Werte ersetzt werden, so dass der Inhalt für die Anzeige für Endbenutzer geeignet ist.

• Wenn "isForDisplay" = false (oder nicht gesetzt), enthält die API-Antwort unverarbeitete Variablen und Snippets, die für die direkte Anzeige möglicherweise nicht nützlich sind.

  Wenn das Problem nach dem Ausführen dieser Schritte weiterhin besteht, wenden Sie sich an das Document360-Support-Team, um weitere Unterstützung zu erhalten: Wenden Sie sich an den Document360-Support

Artikelinhalt in der Wissensdatenbank:

Welcome, {{variable.UserName}}! Here’s how to use {{variable.ProductName}}.

API-Antwort ohne "isForDisplay":

"Welcome, {{variable.UserName}}! Here’s how to use {{variable.ProductName}}."

Die Variablen bleiben unverarbeitet, so dass es für die direkte Anzeige ungeeignet ist.

API-Antwort mit "isForDisplay"=true:

"Welcome, John! Here’s how to use Document360."

Schritte zur Behebung:

1. Rufen Sie den Artikelinhalt über die API ab und überprüfen Sie die Antwort.

2. Überprüfen Sie, ob Variablen oder Snippets in der Antwort nicht verarbeitet werden.

3. Stellen Sie sicher, dass die API-Anforderung den "isForDisplay" Parameter enthält. Wenn dies nicht der Fall ist, ändern Sie die Anforderung so, dass sie einschließt "isForDisplay": true.

4. Senden Sie die geänderte API-Anforderung. Beispiel für eine Anforderung:

   {
     "articleId": "12345",
     "isForDisplay": true
   }
   

5. Überprüfen Sie, ob die API-Antwort jetzt die korrekt gerenderten Variablen und Snippets anzeigt.

6. Wenn das Problem weiterhin besteht, stellen Sie sicher, dass das System, das die API-Antwort verarbeitet, den gerenderten Inhalt ordnungsgemäß verarbeitet und anzeigt.

7. Wenn Sie Artikel über die API aktualisieren, übergeben Sie keine vollständig gerenderten Inhalte, um zu vermeiden, dass dynamische Platzhalter durch statische Werte ersetzt werden.

Leerer Text, der in der API-Dokumentation aufgrund des fehlenden Schematyps angezeigt wird

In der API-Dokumentation wird ein leerer Text angezeigt. Die mögliche Ursache für diesen Fehler könnte sein, dass im OpenAPI-Schema das “type": "object” Attribut in einer oder mehreren Objektdefinitionen fehlt.

Schritte zur Behebung:

Stellen Sie sicher, dass jede Objektdefinition in Ihrer OpenAPI-Spezifikation “type": "object”. Dieses Attribut gibt eindeutig an, dass es sich bei der definierten Struktur um ein Objekt handelt, was dazu beiträgt, Klarheit und Konsistenz in Ihrer API-Dokumentation zu wahren. Es ermöglicht API-Dokumentationstools, Anforderungstextparameter, Antwortschemata und andere Objektdefinitionen genau zu rendern, was es Entwicklern erleichtert, Ihre API zu verstehen und mit ihr zu interagieren.

Hilfreiche Links