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 ausliefert, oder ein Unternehmen, das Dutzende interner Microservices betreibt – Document360 verwandelt Ihre OpenAPI-Spezifikation in eine ausgefeilte, interaktive Entwicklerdokumentation, ohne dass individuelle Werkzeuge oder manuelle Formatierungen erforderlich sind.
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 aus einer maschinenlesbaren Spezifikationsdatei abgeleitet ist.
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
| Aspekt | API-Dokumentation | Regelmäßige Dokumentation |
|---|---|---|
| Hauptzielgruppe | Entwickler und technische Integratoren | Endnutzer, interne Teams |
| Struktur | Gesteuert von einer Spezifikationsdatei (OpenAPI, Postman) | Manuell verfasste Artikel |
| Inhaltstyp | Endpunkte, Parameter, Schemata, Authentifizierungsmethoden | Leitfäden, Anleitungen, konzeptionelle Artikel |
| Interaktivität | Live-Tests über Try It! | Statische Messung |
| Versionierung | An API-Spezifikationsversionen gebunden | Redaktionell verwaltet |
| Auto-Generierung | Ja, aus der Spezifikationsdatei | Nein |
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.
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.
Die Try It!- Funktion in Document360 ermöglicht es Ihnen, API-Endpunkte direkt auf der Knowledge Base-Seite zu testen. Die interaktive Konsole ermöglicht es Entwicklern, die notwendigen Parameter einzugeben und API-Aufrufe auszuführen, wodurch Echtzeitantworten erhalten werden, ohne die Dokumentation zu verlassen oder Code schreiben zu müssen.
Der Abschnitt Try It! unterstützt mehrere Sicherheitssysteme gleichzeitig, sodass Nutzer Endpunkte mit kombinierten Authentifizierungsmethoden effektiver testen können.
Webhooks 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.
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. Document360 unterstützt folgende Autorisierungsmethoden:
- Grunde Authentifizierung – Erfordert einen Benutzernamen und ein Passwort, die in der Anfrage übermittelt werden.
- Inhabertoken – Authentifiziert sich mit einem nach der Anmeldung generierten Token.
- API-Schlüssel – Verwendet einen eindeutigen Schlüssel, der in den Anfrageheadern übergeben wird, zur Authentifizierung.
- OAuth2 – Sichert APIs durch verschiedene Flows: Autorisierungscode, PKCE, Client-Zugangsdaten und Implicit.
- OpenID Connect – Erweitert OAuth2 durch Hinzufügen der Benutzeridentitätsverifikation.
OAuth2 und OpenID Connect: zusätzliche Konfiguration
Wenn man mit APIs arbeitet, die OAuth2 oder OpenID Connect verwenden, sind zwei Einstellungen erforderlich, damit Try It! korrekt funktioniert:
- Umleiten der URI – Setze dies in deinem OAuth-Anbieter auf das Format
domain/oauth. Zum Beispiel:https://apidocs.document360.com/oauth. - Stille Verlängerung – Document360 aktualisiert das Autorisierungstoken automatisch im Hintergrund während aktiver Try It!-Sitzungen, sodass Nutzer sich nicht manuell erneut authentifizieren müssen.
FAQ
Wie unterscheidet sich die API-Dokumentation von der regulären Dokumentation?
Die API-Dokumentation ist speziell darauf ausgelegt, Endpunkte, Authentifizierung und Integrationen zu erklären. Es ist getrennt von Standardartikeln zur Wissensdatenbank und nützlich für Inhalte, die sich an Entwickler richten.
Was ist eine API-Referenz?
Eine API-Referenz ist eine Dokumentationsressource, die umfassende Informationen über die Funktionen, Klassen, Methoden, Parameter, Rückgabetypen und andere Komponenten einer API liefert. Es ist ein Leitfaden oder Handbuch für Entwickler, die die API in ihre Anwendungen integrieren oder nutzen möchten.
Welche unterstützten Dateiformate für die Spezifikation gibt es?
Du kannst deine Spezifikationsdatei als URL-, JSON-, YAML- oder YML-Datei hochladen. Document360 unterstützt OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1 und Postman API-Spezifikationen.
Wie viele API-Referenzen kann ich erstellen?
Innerhalb jedes API-Arbeitsbereichs können Sie maximal 3 API-Referenzen erstellen.
Wie ist die Standardreihenfolge der Kategorien beim Hochladen einer OpenAPI-Spezifikationsdatei?
Kategorien in Document360 werden basierend auf der in Ihrer Spezifikationsdatei definierten Tag-Reihenfolge erstellt. Wenn deine Spezifikation zum Beispiel Tags in der Reihenfolge Haustier, Speichern, Nutzer definiert – erscheinen die Kategorien in derselben Reihenfolge.
Die Option "Probier es!" ist auf der Knowledge Base-Seite nicht verfügbar. Was könnte der Grund sein?
Wenn die Try It!- Funktion nicht sichtbar ist, stelle sicher, dass sowohl die Servervariable als auch die Server-URL korrekt in deiner API-Spezifikationsdatei definiert sind. Ohne diese Funktionen funktioniert die Funktion nicht.
Können API-Referenz-Dropdown-Werte über die Benutzeroberfläche geändert werden?
Nein. Änderungen an API-Referenzelementen wie Dropdown-Werten können nur über die OpenAPI-Spezifikationsdatei vorgenommen werden. Das Ändern dieser Werte über die Benutzeroberfläche wird derzeit nicht unterstützt.
Verwandte Videos
Erleben Sie unsere moderne API-Dokumentation in Document360
Teste API-Endpunkte direkt aus der Dokumentation mit Try It!
Zusätzliche Informationen
Lesen Sie unseren Blog auf - Einführung der API-Dokumentation: Verbessern Sie Ihr API-Erlebnis