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 erstellen:

• 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. Ihre API-Spezifikationsdatei wird hochgeladen und die API-Dokumentation wird generiert.

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, integriert

Du kannst die API-Referenz in deinen CI/CD-Pipelines mit Hilfe deiner d360-npm-Pakete neu synchronisieren. D360 ist das Kommandozeilen-Tool, 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

API-Referenz herunterladen

HINWEIS

Um die API-Dateien herunterzuladen, stellen Sie sicher, dass in den Einstellungen des Knowledge Base Portals der Referenzschalter "Download-API-Anzeigen anzeigen " aktiviert ist.

Fehlerbehebung

Fehlende oder falsche Server-URL in OpenAPI

 Fehler: Dieser Fehler tritt auf, wenn die Server-URL fehlt oder in der OpenAPI-Spezifikation falsch konfiguriert ist. Infolgedessen wissen API-Nutzer nicht, wohin sie API-Anfragen senden sollen, und die Schaltfläche "Probieren Sie es" kann in der API-Dokumentation nicht verfügbar sein. Die Ursache ist typischerweise ein fehlender oder falscher servers Abschnitt in der OpenAPI-Spezifikation.

Schritte zur Lösung

Um dieses Problem zu lösen, stellen Sie sicher, dass die OpenAPI-Spezifikation die korrekte 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. Für regionsbasierte APIs definieren Sie 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 (z. B. Postman, cURL) bei Anfragen die korrekte Server-URL verwenden.

HINWEIS

Die oben genannten URLs sind Beispiele. Bitte beachten Sie Ihre spezifische API-Konfiguration für die korrekte Server-URL.

Beispiel:

YAML-Beispiel für fehlende Angaben 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 servers Abschnitt korrekt in der OpenAPI-Spezifikation definiert ist, um zu verhindern, dass API-Konsumenten manuell API-Anfrage-URLs erstellen müssen.

401 Unautorisierter Fehler von falscher Server-URL

Fehler: Dieser Fehler tritt auf, wenn API-Anfragen eine 401-unautorisierte Antwort zurückgeben. Typischerweise passiert es, wenn bei API-Anfragen die falsche Server-URL verwendet wird. Zum Beispiel führt die Verwendung https://apihub.document360.io statt von https://apihub.us.document360.io zu Authentifizierungsfehlern.

Schritte zur Lösung:

Um dieses Problem zu lösen, folgen Sie diesen Schritten, um die korrekte Nutzung der Server-URLs und die korrekte Authentifizierung sicherzustellen:

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

2. Bestätigen Sie, dass die korrekte Client-ID und das korrekte Client-Geheimnis verwendet werden.

Beispiel für eine korrekte API-Anfrage:

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

HINWEIS

Die obige URL ist ein Beispiel. Bitte beachten Sie Ihre spezifische API-Konfiguration für die korrekte Server-URL.

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

Fehlende Server-URL in der API-Dokumentation

Fehler: Dieses Problem tritt auf, wenn API-Konsumenten unsicher sind , welche Basis-URL sie für ihre Anfragen verwenden sollen. Dies passiert typischerweise, wenn die Dokumentation die Server-URL nicht klar angibt, obwohl sie in der OpenAPI-Spezifikation korrekt konfiguriert sein könnte.

Schritte zur Lösung:

Um Verwirrung zu vermeiden und sicherzustellen, dass API-Konsumenten die korrekte Basis-URL kennen:

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

Beispiele:

Vergleichstabelle: Server-URL vorhanden vs. fehlend

HINWEIS

Die oben genannten URLs sind Beispiele. Bitte beachten Sie Ihre spezifische API-Konfiguration für die korrekte Server-URL.

Um dieses Problem zu vermeiden, stellen Sie sicher, dass die API-Dokumentation die Server-URL klar angibt, um Verwechslungen zu vermeiden.

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

Fehler:

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

Schritte zur Lösung:

Um den 403-Fehler zu beheben, folgen Sie diesen Schritten:

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. Während des Importprozesses überprüfen Sie, ob Warnungen im Zusammenhang mit der Bearer-Authentifizierung ausgelöst werden, und adressieren 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 mit Escaping (\") bestimmte Zeichen sicher handhabt. Dieses Entkommen verändert Zeichen wie Anführungszeichen, Backslashes und Newlines, um Fehler bei der Datenübertragung zu vermeiden. Wenn jedoch die entgangenen Zeichen nicht zurück (nicht entfesselt) werden, kann die HTML-Struktur brechen, was beim Rendern zu Stylingproblemen führt.

Zum Beispiel ein einfacher HTML-Absatz:

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

Könnte in der JSON-Antwort erscheinen als:

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

Die entweichten doppelten Anführungszeichen (\") stellen sicher, dass das JSON gültig bleibt, aber wenn es nicht unescape ist, kann das HTML nicht korrekt dargestellt werden.

Schritte zur Lösung

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

2. Suchen Sie in der JSON-Antwort nach entkommenen Charakteren, zum Beispiel:

   • \" (entkommen doppelte Anführungszeichen)

   • \\ (entkommene Rückschläge)

   • \n (Zeilenzeile)

   • \t (Tab)

3. Entscape den JSON-Inhalt, bevor du ihn renderst. Dadurch wird die ursprüngliche HTML-Struktur wiederhergestellt.

4. Überprüfe das Styling nach dem Unescape, um sicherzustellen, dass der Inhalt korrekt erscheint.

5. Wenn das Problem weiterhin besteht, prüfen Sie, ob weitere Änderungen in Ihrem Code die API-Antwort verändern.

   

   Sobald das HTML ordnungsgemäß unescaped ist, wird es wie erwartet angezeigt und verhindert so Stilabweichungen.

Variablen und Schnipsel werden in der API-Antwort nicht gerendert

Beim Abrufen von Artikelinhalten über die API können Variablen und Ausschnitte unverarbeitet erscheinen (z. B. statt tatsächlicher {{variable.UserName}} Werte). Dies geschieht typischerweise, wenn der Parameter "isForDisplay" nicht korrekt gesetzt ist.

• Wenn "isForDisplay" = true, liefert die API den Artikelinhalt zurück, wobei alle Variablen und Schnipsel vollständig gerendert sind. Das bedeutet, dass die Platzhalter durch tatsächliche Werte ersetzt werden, wodurch die Inhalte für Endnutzer sichtbar sind.

• Wenn "isForDisplay" = false (oder nicht), enthält die API-Antwort unverarbeitete Variablen und Schnippel, die für die direkte Darstellung 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, was sie für die direkte Darstellung ungeeignet macht.

API-Antwort mit "isForDisplay"=true:

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

Schritte zur Lösung:

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

2. Überprüfe, ob Variablen oder Schnipsel in der Antwort unverarbeitet erscheinen.

3. Stellen Sie sicher, dass die API-Anfrage den Parameter "isForDisplay" enthält. Falls fehlt, ändere die Anfrage so, dass sie einfließt "isForDisplay": true.

4. Senden Sie die modifizierte API-Anfrage. Beispielwunsch:

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

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

6. Wenn das Problem weiterhin besteht, stellen Sie sicher, dass das System, das die API-Antwort verarbeitet, die gerenderten Inhalte korrekt behandelt und darstellt.

7. Beim Aktualisieren von Artikeln über die API sollten vollständig gerenderte Inhalte nicht vollständig gerendert werden, um den Austausch dynamischer Platzhalter durch statische Werte zu vermeiden.

Leerer Körper in der API-Dokumentation aufgrund fehlender Schema-Typ angezeigt

Die API-Dokumentation zeigt einen leeren Körper an. Die mögliche Ursache für diesen Fehler könnte sein, dass dem OpenAPI-Schema das Attribut “type": "object” in einer oder mehreren Objektdefinitionen fehlt.

Schritte zur Lösung:

Stellen Sie sicher, dass jede Objektdefinition in Ihrer OpenAPI-Spezifikation enthält “type": "object”. Dieses Attribut legt klar an, dass die definierte Struktur ein Objekt ist, was dazu beiträgt, Klarheit und Konsistenz in Ihrer API-Dokumentation zu gewährleisten. Es ermöglicht API-Dokumentationstools, Anfrage-Body-Parameter, Antwortschemata und andere Objektdefinitionen genau darzustellen, was es Entwicklern erleichtert, Ihre API zu verstehen und mit ihr zu interagieren.

Problem beim Hinzufügen einer API-Referenz

Fehler: API-Referenz kann nicht hinzugefügt werden. Diese Operation kann nicht durchgeführt werden. Bitte stellen Sie sicher, dass Sie eine gültige Spezifikationsdatei eingereicht haben.

Die mögliche Ursache könnte sein, dass die hochgeladene Spezifikationsdatei (YAML) fehlerhaft und kein gültiges OpenAPI 3.0 YAML ist. Dies passiert oft, wenn die Datei aus einem Rich-Text-Editor kopiert oder exportiert wird, was Formatierungsprobleme verursacht.

Schritte zur Lösung:

1. Validiere deine Spezifikationsdatei: Öffne deine YAML-Datei in einem Tool wie Swagger Editor oder einem Code-Editor, um Fehler oder Formatierungsfehler zu überprüfen.

2. Achten Sie auf unerwünschte Formatierungszeichen: Prüfen Sie Zeichen wie \f0\fs24 oder nachfolgende Backslashes \ , die beim Kopieren und Einfügen aus einer Rich-Text-Quelle eingeführt wurden. Diese können das YAML-Format zerstören.

3. Bereinigen Sie die Datei: Verwenden Sie einen einfachen Text- oder Code-Editor, um spezielle Formatierungszeichen zu entfernen. Vermeide es, Textverarbeitungsprogramme beim Bearbeiten oder Speichern von YAML-Dateien zu verwenden.

4. Die Datei erneut hochladen: Nachdem Sie die Datei bereinigt und sichergestellt haben, dass es ein gültiges OpenAPI 3.0 YAML ist, versuchen Sie, sie erneut hochzuladen.

Hilfreiche Links