Erste Schritte mit der API-Dokumentation

Pläne zur Unterstützung der API-Dokumentation

Die API Dokumentationsfunktion in Document360 bietet eine Komplettlösung für die Erstellung und Verwaltung von API-Referenzen. Mit dieser Funktion können Sie eine qualitativ hochwertige API-Dokumentation erstellen, die Benutzern hilft, Ihre APIs zu verstehen und effektiv mit ihnen zu arbeiten. Sie können diese Dokumentation generieren, indem Sie die API-Spezifikationsdatei aus einer URL, einer JSON/YAML/YML-Datei hochladen oder in einen CI/CD-Flow integrieren.

Darüber hinaus können Sie mit der Funktion "Try it!" in Document360 API-Endpunkte direkt auf dem Knowledge base sitetesten. Die interaktive Konsole auf der Wissensdatenbank-Website ermöglicht es Entwicklern, die erforderlichen Parameter einzugeben und API-Aufrufe auszuführen, um Antworten in Echtzeit zu erhalten. Diese Funktion ist nützlich, um Fehler zu beheben und zu verstehen, wie sich eine API verhält, ohne die Dokumentation zu verlassen oder Code zu schreiben.

Onboarding der API-Dokumentation

Bei der Registrierung für Document360 wählen Benutzer ihren primären Anwendungsfall in Schritt 1 des Onboarding-Prozesses aus. Für Benutzer, die API-Dokumentation erstellen möchten, bietet Document360 ein optimiertes Onboarding-Erlebnis. Wenn Sie die API-Dokumentation als Anwendungsfall auswählen, werden Sie zum API-Einrichtungsablauf weitergeleitet, wo Sie API-Referenzen mit den verfügbaren Optionen erstellen können.

In Schritt 2 des Onboarding-Flows haben Sie drei Optionen zum Erstellen einer API-Referenz:

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

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

• Probieren Sie eine Beispiel-API-Datei für eine Tierhandlung aus: Wenn Sie keine API-Datei zur Verfügung haben, können Sie die von Document360 angebotene Beispieldatei (Tierhandlungs-API) verwenden , um Ihren Arbeitsbereich zu füllen.

Hochladen einer API-Definitionsdatei

Um eine API-Referenz aus einer API-Definitionsdatei zu erstellen, wählen Sie das Optionsfeld API-Datei hochladen aus. Klicken Sie anschließend auf Von meinem Gerät hochladen oder ziehen Sie Ihre API-Spezifikationsdatei per Drag & Drop von Ihrem Gerät.

ANMERKUNG

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

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

• Wenn inder hochgeladenen Datei y Warnungen/Warnungen erkannt werden, wird während des Onboardings eine allgemeine Übersicht angezeigt. Ausführliche Details finden Sie im Wissensdatenbank-Portal im Abschnitt "Protokolle" unter "Weitere Optionen in API-Referenzen".

• Wenn in der hochgeladenen Datei ein Fehler erkannt wird (z. B. nicht unterstütztes Dateiformat), ersetzen Sie die hochgeladene Datei durch eine andere Datei.

Eingeben einer API-Dokumentations-URL

Um einen API-Verweis aus einer API-Dokumentations-URL zu erstellen, wählen Sie das Optionsfeld Aus URL erstellen aus. Geben Sie als Nächstes die URL für Ihre OpenAPI-Datei in das Feld URL zu Ihrer API-Definition ein. Document360 ruft die API-Struktur ab und verarbeitet sie. Ähnlich wie beim Hochladen von Dateien

• Wenn Warnungen/Warnungen erkannt werden, können Sie diese im Wissensdatenbankportal im Abschnitt Protokolle unter Weitere Optionen in der API-Referenzanzeigen.

• Wenn ein Fehler erkannt wird (z. B. Ungültige URL), geben Sie die gültige URL für Ihre OpenAPI-Datei ein.

Überspringen der API-Einrichtung

Wenn Sie die Option Beispiel-API-Datei für Tierhandlungen ausprobieren auswählen,

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

• Dies wird im Entwurfsmodus verfügbar sein. Sie können die Endpunkte vor der Veröffentlichung überprüfen oder Ihre Spezifikationsdatei hochladen und später veröffentlichen.

Personalisieren Sie Ihre Wissensdatenbank

In Schritt 3 können Sie Ihre bevorzugte Website-URL eingeben. Wenn Sie diesen Schritt überspringen möchten, wird die Domain standardmäßig auf die Domain gesetzt, die mit Ihrer Registrierungs-E-Mail verknüpft ist.

Marken-Richtlinien

In Schritt 4 werden Ihr Projektname, die Standardsprache, das Branding-Logo und die Markenfarben automatisch basierend auf der von Ihnen 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, wenn andere Sprachen die Sprache Ihres Browsers nicht unterstützen.

ANMERKUNG

• Wenn Sie Spanisch oder brasilianisches Portugiesisch als Standardsprache auswählen, wird die Sprache des Portals auf Spanisch oder brasilianisches Portugiesisch festgelegt. Andernfalls ist Englisch die Standardsprache.

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

Festlegen des Datenschutzes für die Dokumentation

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

• Privat: Beschränken Sie den Zugriff auf die Wissensdatenbank, sodass nur Teamkonten den Inhalt anzeigen und mit ihm interagieren können, um ihn sicher und intern zu halten.

• Öffentlich: Machen Sie die Wissensdatenbank für alle, auch für externe Benutzer, zugänglich, um einen offenen Zugang zu allen Inhalten zu ermöglichen.

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

Klicken Sie abschließend auf Weiter , um Ihren API-Onboarding-Ablauf abzuschließen.

Sie werden zum Arbeitsbereich für die API-Dokumentation weitergeleitet, in dem Folgendes gilt:

• Sie sehen die API-Referenz der API-Spezifikation, die Sie während des Onboardings angegeben haben.

• Wenn Sie keine API-Spezifikation angegeben haben, ist eine Beispiel-API-Referenz (Tierhandlungs-API) im Entwurfsmodus 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 mithilfe von Autorisierungstechniken, die den Zugriff und die Berechtigungen steuern. Document360 unterstützt verschiedene Autorisierungsmethoden, um Ihre API zu sichern, darunter:

• Standardauthentifizierung: Erfordert einen Benutzernamen und ein Kennwort, die in der Anforderung übergeben werden.

• Bearertoken: Authentifiziert sich mit einem Token, das nach der Anmeldung generiert wird.

• API-Schlüssel: Verwendet einen eindeutigen Schlüssel, der in den Anforderungsheadern für die Authentifizierung übergeben wird.

• OAuth2: Sichert APIs über verschiedene Flows, z. B. Autorisierungscode, PKCE, Clientanmeldeinformationen und implizite Flows.

• OpenID Connect: Erweitert OAuth2 durch Hinzufügen einer Überprüfung der Benutzeridentität.

Überlegungen zur Autorisierung (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, zu der der Benutzer nach Abschluss eines Autorisierungsflows umgeleitet wird. Stellen Sie sicher, dass Sie den URI im folgenden Format festlegen: domain/oauth. Beispiel: https://apidocs.document360.com/oauth.

• Automatische Erneuerung: Bei der unbeaufsichtigten Verlängerung wird das Autorisierungstoken automatisch im Hintergrund aktualisiert, sodass sich Benutzer während ihrer Sitzung nicht erneut authentifizieren müssen. Dadurch bleibt die Sitzung ohne Unterbrechung aktiv. Um zu verhindern, dass die Autorisierung während Sitzungen abläuft, in denen Benutzer mit der Funktion "Try It!" interagieren, erneuert Document360 das Aktualisierungstoken automatisch im Hintergrund. Dadurch wird sichergestellt, dass sich Benutzer nicht erneut manuell authentifizieren müssen.

Kauf

Sie haben Zugriff auf 1 API-Arbeitsbereich als Teil aller kostenpflichtigen Document360-Pläne (Professional, Business und Enterprise). Wenn Sie zusätzliche API-Arbeitsbereiche erwerben möchten,

1. Navigieren Sie zu Settings() > Wissensdatenbank-Portal > Abrechnung > Mein Plan.

2. Klicken Sie auf Add-on kaufen.

3. Fügen Sie die gewünschte Anzahl von API-Dokumentationsarbeitsbereichen hinzu. Überprüfen Sie die Kosten des Add-ons und den fälligen Betrag.

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

Fehlerbehebung

Probleme beim API-Zugriff

Fehler: Fehler 400 – Der API-Zugriff ist deaktiviert. Bitte wenden Sie sich an Ihren Projektadministrator.

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

Schritte zur Behebung:

1. Navigieren Sie zu Settings() > KI-Funktionen > Eddy AI im Wissensdatenbank-Portal.

2. Stellen Sie sicher, dass im Abschnitt AI Search Suite das Kontrollkästchen Ö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

Verwandte Videos

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

Testen Sie API-Endpunkte direkt aus der Dokumentation mit der Funktion "Try it"

Zusatzinformation

Einführung in die API-Dokumentation: Verbessern Sie Ihr API-Erlebnis - Klicken Sie hier, um zu lesen