Einstieg mit der API-Dokumentation

Die API in Document360 bietet eine vollständige Lösung zum Erstellen und Verwalten von API-Referenzen. Diese Funktion ermöglicht es Ihnen, hochwertige API-Dokumentationen zu erstellen, die den Nutzern hilft, Ihre APIs effektiv zu verstehen und zu nutzen. Sie können diese Dokumentation erstellen, indem Sie die API-Spezifikationsdatei aus einer URL, einer JSON/YAML/YML-Datei hochladen oder sich in einen CI/CD-Fluss integrieren. Document360 unterstützt OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1 und Postman-Sammlungen.

Zusätzlich ermöglicht die Funktion "Probieren Sie es!" in Document360, API-Endpunkte direkt auf der Knowledge base site zu testen. Die interaktive Konsole auf der Knowledge Base-Seite ermöglicht es Entwicklern, die notwendigen Parameter einzugeben und API-Aufrufe auszuführen, wodurch Echtzeitantworten erhalten werden. Diese Funktion ist hilfreich bei der Fehlersuche und beim Verständnis des Verhaltens einer API, ohne die Dokumentation zu verlassen oder Code zu schreiben.

HINWEIS

Der Abschnitt Try It! unterstützt mehrere Sicherheitssysteme gleichzeitig, sodass Nutzer Endpunkte mit kombinierten Authentifizierungsmethoden effektiver testen können.

Webhooks (Events) in OpenAPI 3.1

Document360 unterstützt Webhooks, die in OpenAPI 3.1 definiert sind. Webhooks erscheinen mit einem Ereignis-Icon in deiner API-Referenz und enthalten einen Payload-Abschnitt basierend auf deinem Schema. Wenn kein Beispiel bereitgestellt wird, zeigt Document360 ein Standardbeispiel und eine Sample-Nutzlast an. Try It ist nicht für Webhooks verfügbar. Webhooks werden für Dateiuploads, URL-Importe und CI/CD-Flows unterstützt.

API-Dokumentations-Onboarding

Bei der Anmeldung bei Document360 wählen Nutzer ihren Hauptanwendungsfall in Schritt 1 des Onboarding-Flusses. Für Nutzer, die API-Dokumentation erstellen möchten, bietet Document360 ein optimiertes Onboarding-Erlebnis. Wenn du die API-Dokumentation als Anwendungsfall auswählst, wirst du zum API-Setup-Flow weitergeleitet, wo du mit den verfügbaren Optionen API-Referenzen erstellen kannst.

In Schritt 2 des Onboarding-Flows haben Sie drei Optionen, um eine API-Referenz zu erstellen:

• API-Datei hochladen: Unterstützt JSON/YAML/YML-Dateien (OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1 und Postman-Sammlungen).

• Aus URL erstellen: Ruft automatisch die API-Spezifikation von der gehosteten URL ab.

• Probieren Sie eine Beispiel-API-Datei für Tierläden: Wenn Sie keine API-Datei bereit haben, können Sie die Beispieldatei (Pet Store API) von Document360 verwenden, um Ihren Arbeitsbereich zu füllen.

Hochladen einer API-Definitionsdatei

Um eine API-Referenz aus einer API-Definitionsdatei zu erstellen, wählen Sie die Schaltfläche "API-Datei hochladen". Als Nächstes klickst du auf 'Von meinem Gerät hochladen ' oder ziehst deine API-Spezifikationsdatei von deinem Gerät per Drag & Drop.

HINWEIS

Die für die API-Definitionsdatei unterstützten Dateiformate sind JSON, YAML oder YML.

Das System analysiert die Datei und erzeugt automatisch die API-Referenz.

• Wenn inder hochgeladenen Datei Warnungen/Warnungen erkannt werden, wird während des Onboardings eine übergeordnete Übersicht angezeigt. Sie können ausführliche Details im Knowledge Base-Portal im Logs-Bereich unter Mehr-Optionen innerhalb der API-Referenzen einsehen.

• Wenn in der hochgeladenen Datei ein Fehler festgestellt wird (zum Beispiel nicht unterstütztes Dateiformat), ersetzen Sie die hochgeladene Datei durch eine alternative Datei.

Eingabe einer API-Dokumentations-URL

Um eine API-Referenz aus einer API-Dokumentations-URL zu erstellen, wählen Sie die Schaltfläche "Aus URL erstellen " aus. Gib als Nächstes die URL deiner OpenAPI-Datei in das URL zu deinem API-Definitionsfeld ein. Document360 wird die API-Struktur abrufen und verarbeiten. Ähnlich wie beim Hochladen von Dateien,

• Wenn Warnungen/Warnungenerkannt werden, können Sie sie im Knowledge Base-Portal im Logs-Bereich unter Mehr-Optionen innerhalb der API-Referenzen ansehen. Sie können ausführliche Details im Knowledge Base-Portal im Logs-Bereich unter Mehr-Optionen innerhalb der API-Referenzen einsehen.

• Wenn ein Fehler erkannt wird (zum Beispiel eine ungültige URL), gib die gültige URL für deine OpenAPI-Datei ein.

API-Einrichtung überspringen

Wenn Sie die Option "Beispiel-Haustierladen-API" wählen ,

• Document360 erstellt automatisch eine Beispiel-API-Referenz (Pet Store API).

• Dies wird im Draft-Modus verfügbar sein. Du kannst die Endpunkte vor der Veröffentlichung überprüfen oder deine Spezifikationsdatei hochladen und später veröffentlichen.

Personalisieren Sie Ihre Wissensdatenbank

In Schritt 3 können Sie Ihre bevorzugte Website-URL eingeben. Wenn du diesen Schritt überspringen möchtest, wird die Domain standardmäßig auf die mit deiner Registrierungs-E-Mail verknüpfte Domain verwendet.

Markenrichtlinien

In Schritt 4 werden dein Projektname, deine Standardsprache, dein Branding-Logo und die Markenfarben automatisch basierend auf deiner angegebenen URL festgelegt. Sie können diese Felder jedoch bei Bedarf bearbeiten. Die Spracheinstellungen Ihres Browsers bestimmen die Standardsprache. Englisch wird standardmäßig ausgewählt, falls andere Sprachen die Sprache deines Browsers nicht unterstützen.

HINWEIS

• Wenn Sie Spanisch oder brasilianisches Portugiesisch als Standardsprache wählen, wird die Portalsprache auf Spanisch oder brasilianisches Portugiesisch eingestellt. Andernfalls wird Englisch die Standardsprache sein.

• Das Branding-Logo und die Primär- und Sekundärfarben werden von Ihrer Website extrahiert. Wenn Sie diesen Schritt überspringen , wird der Projektname aus Ihrer Registrierungs-E-Mail abgeleitet, und das Standardlogo und die Farben von Document360 werden angewendet.

Dokumentation Privatsphäre festlegen

In Schritt 5 können Sie die gewünschten Datenschutzeinstellungen für Ihre Seite auswählen:

• Privat: Den Zugriff auf die Wissensdatenbank einschränken, sodass nur Teamkonten die Inhalte einsehen und mit ihnen interagieren können, wodurch sie sicher und intern bleiben.

• Öffentlich: Machen Sie die Wissensdatenbank für alle, einschließlich externer Nutzer, zugänglich, sodass offener Zugang zu allen Inhalten möglich ist.

• Gemischt: Kombiniert privaten und öffentlichen Zugang, indem einige Bereiche der Wissensdatenbank für die Öffentlichkeit sichtbar sind, während andere Bereiche nur auf Teamkonten beschränkt bleiben.

Klicken Sie schließlich auf Weiter, um Ihren API-Onboarding-Flow abzuschließen.

Sie werden zum API-Dokumentations-Arbeitsbereich weitergeleitet, wo:

• Sie sehen die API-Referenz der API-Spezifikation, die Sie beim Onboarding angegeben haben.

• Wenn Sie keine API-Spezifikation bereitgestellt haben, ist im Entwurfsmodus eine Beispiel-API-Referenz (Pet Store API) verfügbar.  

Autorisierungstechniken

Bei der Interaktion mit einer API ist es wichtig sicherzustellen, dass nur autorisierte Benutzer auf bestimmte Daten zugreifen oder bestimmte Aktionen ausführen können. Dies geschieht durch Autorisierungstechniken, die Zugriff und Berechtigungen steuern. Document360 unterstützt verschiedene Autorisierungsmethoden zur Sicherung Ihrer API, darunter:

• Grunde Authentifizierung: Erfordert Benutzername und Passwort, die in der Anfrage übermittelt werden.

• Inhaber-Token: Authentifiziert sich mit einem nach der Anmeldung generierten Token.

• API-Schlüssel: Verwendet einen eindeutigen Schlüssel, der in den Request-Headern übergeben wird, zur Authentifizierung.

• OAuth2: Sichert APIs durch verschiedene Flows wie Autorisierungscode, PKCE, Client-Zugangsdaten und implizite Flows.

• OpenID Connect: Erweitert OAuth2 durch Hinzufügen der Benutzeridentitätsverifikation.

Autorisierungsüberlegungen (OAuth2 und OpenID)

Bei der Arbeit mit APIs, die OAuth2 oder OpenID für die Autorisierung verwenden, sind bestimmte Einstellungen für die ordnungsgemäße Funktionalität unerlässlich.

• Umleitungs-URI: Dies ist die URL, auf die der Benutzer nach Abschluss eines Autorisierungsprozesses weitergeleitet wird. Stellen Sie sicher, dass Sie die URI im Format setzen: domain/oauth. Zum Beispiel: https://apidocs.document360.com/oauth.

• Stille Verlängerung: Die stille Verlängerung aktualisiert automatisch das Autorisierungstoken im Hintergrund, sodass Nutzer sich während ihrer Sitzung nicht erneut authentifizieren müssen. Das hält ihre Sitzung ohne Unterbrechung aktiv. Um zu verhindern, dass die Autorisierung während Sitzungen abläuft, in denen Nutzer mit der Try It!- Funktion interagieren, erneuert Document360 das Aktualisierungstoken automatisch im Hintergrund. Das stellt sicher, dass Nutzer sich nicht manuell erneut authentifizieren müssen.

Anschaffung

Sie haben Zugang zu einem API-Arbeitsbereich als Teil aller kostenpflichtigen Document360-Tarife (Professional, Business und Enterprise). Wenn Sie zusätzliche API-Arbeitsbereiche kaufen möchten,

1. Navigieren Sie zu () > Knowledge Base-Portal > Abrechnung > meinem Plan.

2. Klicken Sie auf Add-on kaufen.

3. Füge die gewünschte Anzahl von API-Dokumentations-Arbeitsbereichen hinzu. Überprüfen Sie die Kosten des Zusatzes und den fälligen Betrag.

4. Klicken Sie auf Zahlung bestätigen , um mit der Zahlung fortzufahren.

Fehlerbehebung

API-Zugriffsprobleme

Fehler: 400 Fehler – API-Zugriff ist deaktiviert. Bitte kontaktieren Sie Ihren Projektadministrator.

Dieser Fehler tritt auf, wenn der öffentliche API-Zugriff in den Projekteinstellungen deaktiviert wird.

Schritte zur Lösung:

1. Navigiere zu () > KI-Einstellungen > Eddy AI-Einstellungen im Knowledge Base-Portal.

2. Im Bereich KI-Suchsuiten stellen Sie sicher, dass das Kästchen für die öffentliche API aktiviert ist.

   

3. 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

API-Importprobleme

Fehler: Ungültiges Format – API-Dateihochladen fehlgeschlagen.

Dieser Fehler tritt auf, wenn eine oder mehrere Antworten in der OpenAPI-Spezifikationsdatei den erforderlichen content Abschnitt fehlen.

Obwohl die Datei die Validierung im Swagger Editor bestehen kann, setzt Document360 strenge OpenAPI-Validierungsregeln durch und verlangt, dass alle Antworten explizit den Medientyp (zum Beispiel application/json) und die Schema-Referenz definieren.

Schritte zur Lösung:

1. Öffnen Sie Ihre OpenAPI (Swagger) Spezifikationsdatei in einem Texteditor oder IDE.

2. Finde alle Antwortdefinitionen, die leer sind oder direkt auf ein Schema ohne Block content verweisen.

   Beispiel für eine falsche Antwort:

   responses:
     "200": {}

3. Aktualisieren Sie die Antwortdefinition, um einen Inhaltsabschnitt mit dem passenden Medientyp und der entsprechenden Schema-Referenz einzuschließen.

   Beispiel für eine korrekte Antwort:

   responses:
     "200":
       description: OK
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/UserGroupFetchResponse"

4. Speichere die Datei und versuche, sie erneut in Document360 hochzuladen.

Zusammenfassung und Tags, die nach dem Import einer API-Spezifikation nicht angezeigt werden

Fehler: Die importierten Endpunkte zeigen nicht die korrekten Titel an oder erscheinen nicht unter den erwarteten Tag-Ordnern.

Dieses Problem tritt auf, wenn die summary und-Felder tags in der OpenAPI-Spezifikation auf Pfadebene definiert sind und nicht unter dem Operationsobjekt (get, post, put, oder delete).

Zusätzlich muss das Feld tags immer als Array geschrieben werden, selbst wenn nur ein Tag verwendet wird.

Schritte zur Lösung:

1. Öffnen Sie Ihre OpenAPI-Spezifikationsdatei in einem Texteditor.

2. Verschieben Sie die Zusammenfassungs- und Tag-Felder innerhalb jedes Operationsobjekts.

3. Stellen Sie sicher, dass der Tag-Wert als Array geschrieben wird.

   Falsches Beispiel:

   /dms/modules/{module-name}/types/logical/{logical-type}:
     summary: Type & Logical type
     tags: Logical Types
     get:
       ...
   

   Korrektes Beispiel:

   /dms/modules/{module-name}/types/logical/{logical-type}:
     get:
       summary: Type & Logical type
       tags: ["Logical Types"]
       ...
   

4. Nachdem Sie diese Updates vorgenommen haben, speichern Sie die Datei und importieren Sie sie erneut in Document360.

   Die importierten Artikel verwenden nun den summary Wert als Artikeltitel, und tagbasierte Ordner werden korrekt erstellt.

Verwandte Videos

Erleben Sie unsere moderne API-Dokumentation in Document360 wie nie zuvor

Testen Sie API-Endpunkte direkt aus der Dokumentation mit der Funktion "Probieren Sie es"

Zusätzliche Informationen

Einführung der API-Dokumentation: Verbessern Sie Ihr API-Erlebnis – Klicken Sie zum Lesen