Einstieg mit der API-Dokumentation

Überblick

Die API-Dokumentationsfunktion von Document360 bietet Ihnen eine komplette, durchgängige Lösung für das Veröffentlichen, Verwalten und Testen von API-Referenzen. Egal, ob Sie ein Startup sind, das seine erste öffentliche API veröffentlicht, oder ein Unternehmen, das Dutzende interner Microservices unterhält – Document360 verwandelt Ihre OpenAPI-Spezifikation in ausgefeilte, interaktive Entwicklerdokumentation, ohne dass individuelle Werkzeuge oder manuelle Formatierungen erforderlich sind.

Dieser Artikel behandelt alles, was Sie wissen müssen: das Einrichten Ihrer ersten API-Referenz, die Wahl der richtigen Importmethode, das Absichern von Endpunkten mit Authentifizierung, Live-Tests mit Try It!, die Handhabung von Webhooks, das Ausführen von CI/CD-integrierten Pipelines und das Befolgen von Best Practices, die gute API-Dokumente von wirklich großartigen unterscheiden.

Was ist API-Dokumentation und warum ist sie wichtig?

Die API-Dokumentation ist die technische Referenz, die Entwicklern genau sagt, wie sie mit Ihrer API interagieren sollen: welche Endpunkte existieren, welche Parameter sie akzeptieren, welche Antworten sie zurückgeben und wie die Authentifizierung funktioniert. Im Gegensatz zu allgemeinen Knowledge Base-Artikeln folgen API-Dokumente einem strengen, strukturierten Format, das von einer maschinenlesbaren Spezifikationsdatei abgeleitet ist (wie OpenAPI).

Warum es wichtig ist:

• Verkürzt die Integrationszeit. Clear Docs reduziert das Onboarding von Tagen auf Stunden. Entwickler verbringen weniger Zeit mit Raten und mehr mit dem Bauen.

• Reduziert die Unterstützungsbelastung. Wenn Dokumente die Fragen "Wie authentifiziere ich mich?" und "Was bedeutet ein 422?" beantworten, bekommt Ihr Team weniger Tickets.

• Das baut Vertrauen der Entwickler auf. Unvollständige oder veraltete API-Dokumente deuten auf ein unzuverlässiges Produkt hin. Hochwertige Dokumentation ist ein direktes Signal für Produktqualität.

• Ermöglicht Selbstbedienung. Externe Partner, Kunden und Drittentwickler können integrieren, ohne dass Ihr Team sie unterstützen muss.

API-Dokumentation vs. normale Dokumentation

In Document360 befindet sich die API-Dokumentation in einem dedizierten API-Arbeitsbereich, der von Ihrer Standard-Wissensdatenbank getrennt ist. Dies ermöglicht unterschiedliche Zugriffskontrollen, Routing und Branding für Ihre entwicklerorientierten Inhalte.

Unterstützte Spezifikationsformate

Document360 unterstützt folgende Spezifikationsformate:

• OpenAPI 2.0 (früher Swagger)

• OpenAPI 3.0

• OpenAPI 3.1 (beinhaltet Webhook-Unterstützung)

• Postbotensammlungen

Dateien können als JSON, YAML oder YML hochgeladen werden.

Wahl eines Formats: Wenn du neu anfängst, benutze OpenAPI 3.1. Es ist der aktuelle Standard, unterstützt Webhooks nativ und verfügt über das reichhaltigste Tooling-Ökosystem. Wenn du von einem bestehenden Swagger 2.0-Setup migrierst, akzeptiert Document360 es so, wie es ist, während du schrittweise upgradest.

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 in der hochgeladenen Datei Warnungen entdeckt 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 oder Warnungen erkannt 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. Navigiere 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-KI-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.

Die Startseite der Knowledge Base leitet zu  /apidocs nach dem Konto-Upgrade weiter

Fehler: Die Startseite der Wissensdatenbank leitet auf  /apidocs und die Seite existiert nicht

Dieses Problem tritt auf, wenn ein API-Dokumentationsarbeitsbereich auf Public Reader Access gesetzt wird.

Wenn die Wissensdatenbank aktualisiert wird, kann der API-Dokumentationsarbeitsbereich auf Public Reader Access gesetzt werden. Daher werden Besucher der Startseite der Wissensdatenbank automatisch auf die /apidocs Seite weitergeleitet, die standardmäßig nicht erstellt wird.

Schritte zur Lösung:

1. Navigieren Sie in der linken Navigationsleiste im Knowledge Base zu () > Benutzer & Berechtigungen .

2. Im linken Navigationsfenster navigieren Sie zum Reader-Zugriff.

3. Finde den API-Dokumentations-Arbeitsbereich.

4. Stellen Sie den Reader-Zugriff auf Privat.

Dies stoppt die unbeabsichtigte Weiterleitung und stellt den normalen Zugriff auf die Startseite Ihrer Wissensdatenbank wieder her.

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