Dieser Leitfaden führt Sie durch die Veröffentlichung Ihrer ersten API-Referenz in Document360, vom Hochladen Ihrer Spezifikationsdatei in ein lebendiges, interaktives Entwicklerportal.
Am Ende dieses Artikels haben Sie:
- Eine API-Referenz, die aus Ihrer OpenAPI-Spezifikation generiert wird
- Ihre Endpunkte sind von Entwicklern sichtbar und durchsuchbar
- Die interaktive Konsole Try It! bereit für Live-API-Tests
API-Dokumentation ist für alle kostenpflichtigen Tarife verfügbar. Jeder kostenpflichtige Tarif beinhaltet einen API-Arbeitsbereich. Zusätzliche Arbeitsbereiche können als Add-ons erworben werden.
Voraussetzungen
Stellen Sie vor Beginn sicher, dass Sie Folgendes haben:
- Ein Document360-Konto auf einem professionellen, geschäftlichen oder Unternehmensplan.
- Eine API-Spezifikationsdatei in einem dieser Formate: OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1 oder Postman Collection. Akzeptierte Dateitypen sind JSON, YAML oder YML.
- Zugriff auf das Knowledge Base-Portal mit Berechtigungen zur Erstellung von Inhalten.
Falls Sie noch keine Spezifikationsdatei haben, können Sie dieser Anleitung trotzdem mit der Beispieldatei der Pet Store API folgen, die Document360 bereitstellt. Du wirst während der Einrichtung aufgefordert, es zu verwenden.
Navigiere zum API-Dokumentationsarbeitsbereich
- Melden Sie sich bei Document360 an und öffnen Sie Ihr Projekt im Knowledge Base-Portal.
- Klicken Sie in der linken Navigationsleiste auf API-Dokumentation
{ }. Dies öffnet den dedizierten API-Arbeitsbereich, getrennt von Ihrer Standard-Wissensdatenbank. - Klicken Sie in der oberen Navigationsleiste auf das Dropdown-Menü Erstellen und wählen Sie Neue API. Dies öffnet das Referenzfenster für die neue API.
Du kannst maximal 3 API-Referenzen innerhalb jedes API-Arbeitsbereichs erstellen.
Wähle, wie du deine Spezifikation importierst
Document360 unterstützt zwei Möglichkeiten, Ihre Spezifikationsdatei zu importieren: Dateihochladen und URL-Import. Der CI/CD-Fluss ist keine separate Importmethode; Es ist eine Möglichkeit, eine dieser beiden Methoden zu automatisieren, sodass Ihre Dokumentation automatisch aktualisiert wird, sobald sich Ihre Spezifikation ändert.
| Methode | Wann man es einsetzen sollte | Wie es funktioniert |
|---|---|---|
| Dateihochladen | Die Spezifikationsdatei hast du lokal als JSON, YAML oder YML. | Lade die Datei direkt hoch. Am besten, um schnell loszulegen oder nur selten zu aktualisieren. |
| URL-Import | Deine Spezifikation wird auf einer stabilen öffentlichen oder internen URL gehostet. | Zeigen Sie Document360 auf die URL. Du kannst manuell von derselben URL neu synchronisieren, wann immer sich die Spezifikation ändert. |
| CI/CD-Fluss | Du möchtest, dass die Dokumentation bei jeder Änderung der Spezifikation automatisch aktualisiert wird. | Automatisiert den Datei-Upload oder URL-Import über die d360-CLI in deiner Pipeline. Erfordert Node.js. |
Lade deine Spezifikation hoch
Lade eine Datei hoch
- Im Referenzfenster für neue APIs wählen Sie die Option API-Definition hochladen .
- Klicken Sie auf "Von meinem Gerät hochladen " oder ziehen Sie Ihre Datei per Drag & Drop. Unterstützte Formate: JSON, YAML, YML.
- Document360 parst die Datei und generiert automatisch die API-Referenz. Wenn Warnungen erkannt werden, erscheint ein Abschnitt Warnungen und Warnungen – erweitern Sie ihn, um sie zu überprüfen. Alle Details können Sie später im Abschnitt Logs einsehen.
- Klicken Sie auf Neue API-Referenz, um fortzufahren.
Import von einer URL
- Im Referenzfenster Neue API wählen Sie die Option "Aus URL erstellen " und klicken Sie auf Weiter.
- Geben Sie die URL, die auf Ihre OpenAPI-Spezifikationsdatei zeigt, im URL-Feld ein.
- Document360 holt die Spezifikation ab und verarbeitet sie. Wenn Warnungen erkannt werden, sind sie nach dem Import im Abschnitt Logs verfügbar.
- Klicken Sie auf API-Referenz hinzufügen , um fortzufahren.
Verwenden Sie den CI/CD-Fluss
Diese Option erfordert, dass Node.js auf Ihrem System installiert wird.
- Im Referenzfenster für neue APIs wählen Sie die Option CI/CD Flow aus.
- Kopiere den vollständigen CLI-Befehl, der im Fenster angezeigt wird.
- Im kopierten Befehl ersetzen Sie den
--pathWert durch den vollständigen Pfad zu Ihrer lokalen Spezifikationsdatei oder eine gültige URL, die darauf verweist. Zum Beispiel:
--path=/Users/yourname/projects/api/openapi.yaml
Oder eine URL:
--path=https://example.com/api/openapi.yaml
- Füge den aktualisierten Befehl in dein Terminal ein und drücke Enter. Document360 lädt deine Spezifikation hoch und generiert die API-Dokumentation.
Die erste Zeile des CLI-Befehls (npm install d360 -g) installiert das CLI-Tool Document360. Du musst es nur einmal ausführen. Wenn sie bereits installiert ist, kannst du diese Zeile überspringen.
Wenn Sie Ihren API-Schlüssel neu generieren, müssen Sie den --apiKey Wert in Ihrem CLI-Befehl aktualisieren, bevor Sie ihn erneut ausführen. Der alte Schlüssel wird nicht mehr gültig sein.
Keine Spezifikationsdatei? Verwenden Sie die Beispiel-API von Pet Store
Wenn du keine Spezifikationsdatei bereit hast, wähle Beispiel-Pet Store-API-Datei aus , wenn du dazu aufgefordert wirst. Document360 erstellt automatisch eine Beispiel-API-Referenz im Entwurfsmodus. Du kannst es erkunden und später durch deine eigene Spezifikation ersetzen.
Überprüfen Sie Warnungen und Warnungen
Nachdem Sie Ihre Spezifikation hochgeladen haben, zeigt Ihnen Document360 eine Zusammenfassung der erstellten Kategorien und Artikel sowie aller in Ihrer Datei entdeckten Warnungen oder Warnungen.
- Warnungen und Warnungen bedeuten, dass die Spezifikation importiert wurde, aber einige Elemente werden möglicherweise nicht wie erwartet angezeigt. Sie können die vollständigen Details im Abschnitt Logs überprüfen: Gehen Sie zu Ihrer API-Referenz, klicken Sie auf das Mehr-Symbol
(⋯)und wählen Sie Logs. - Fehler bedeuten, dass der Import fehlgeschlagen ist. Die häufigste Ursache ist ein nicht unterstütztes Dateiformat oder eine ungültige URL. Ersetzen Sie die Datei oder korrigieren Sie die URL und versuchen Sie es erneut.
Veröffentlichen Sie Ihre API-Referenz
Nachdem Ihre Spezifikation erfolgreich verarbeitet wurde:
- Ein Bestätigungsfenster zeigt die Anzahl der erstellten Kategorien und Artikel. Klicken Sie auf Veröffentlichen , um die API-Referenz aktiv zu machen.
- Wenn Sie die Inhalte vor der Veröffentlichung überprüfen möchten, klicken Sie auf Schließen. Ihre API-Referenz wird im Entwurfsmodus gespeichert und im Bereich Kategorien & Artikel sichtbar.
Der Entwurfsmodus ist nützlich, wenn du individuelle Endpunkt-Artikel mit benutzerdefinierten Inhalten hinzufügen möchtest, bevor sie öffentlich gemacht werden. Alle benutzerdefinierten Inhalte, die Sie hinzufügen, werden behalten, wenn Sie Ihre Dokumentation neu generieren oder neu synchronisieren.
Konfigurieren Sie die Authentifizierung für Try It!
Die Try It!-Konsole ermöglicht es Entwicklern, deine API-Endpunkte direkt aus der Dokumentation zu testen. Damit es korrekt funktioniert, muss die Authentifizierungsmethode in Ihrer Spezifikation definiert und in Document360 konfiguriert werden.
Document360 unterstützt die folgenden Authentifizierungsmethoden:
| Methode | Wie es funktioniert |
|---|---|
| Grundlegende Authentifizierung | Benutzername und Passwort wurden im Anfrage-Header weitergegeben. |
| Inhabermarker | Ein nach der Anmeldung generiertes Token wurde im Autorisierungs-Header weitergegeben. |
| API-Schlüssel | Ein eindeutiger Schlüssel wurde in den Anfrage-Headern weitergegeben. |
| OAuth2 | Unterstützt Autorisierungscode, PKCE, Client-Zugangsdaten und implizite Flows. |
| OpenID Connect | Erweitert OAuth2, um eine Benutzeridentitätsverifikation hinzuzufügen. |
Die Try It!-Konsole unterstützt mehrere Sicherheitsschemata gleichzeitig und ermöglicht so das Testen von Endpunkten, die kombinierte Authentifizierungsmethoden erfordern.
OAuth2 und OpenID Connect: zusätzliche Konfiguration
Bei der Verwendung von OAuth2 oder OpenID Connect sind zwei Einstellungen erforderlich:
- URI umleiten – Stelle dies in deinem OAuth-Anbieter auf
domain/oauth. Zum Beispiel:https://apidocs.yourdomain.com/oauth. - Stille Verlängerung — Document360 aktualisiert das Autorisierungstoken während aktiver Try It!-Sitzungen automatisch im Hintergrund, sodass Nutzer sich nicht manuell erneut authentifizieren müssen.
Wenn der Try It!-Button auf deiner Knowledge Base-Seite nicht sichtbar ist, prüfe, ob sowohl die Servervariable als auch die Server-URL korrekt in deiner API-Spezifikationsdatei definiert sind. Ohne diese Funktionen funktioniert die "Versuch es!"-Funktion nicht.
Lesezugang und Privatsphäre einstellen
Kontrollieren Sie, wer Ihre veröffentlichte API-Referenz sehen kann, indem Sie die Leserzugriffseinstellungen konfigurieren.
| Schauplatz | Was es bedeutet |
|---|---|
| Gefreiter | Nur Teamkonten können die API-Referenz einsehen. Verwendung für interne oder nur Partner-APIs. |
| Öffentlich | Jeder kann ohne Authentifizierung auf die API-Referenz zugreifen. |
| Gemischt | Einige Bereiche sind öffentlich, andere sind auf Team-Konten beschränkt. |
Um den Lesezugriff zu konfigurieren, navigieren Sie im Knowledge Base Portal zu Einstellungen > Benutzer & Berechtigungen > Leserzugriff und suchen Sie Ihren API-Dokumentationsarbeitsbereich.
Ein Besuch /apidocs vor der Veröffentlichung von Endpunkt-Artikeln liefert einen 404-Fehler zurück – es gibt noch keinen Inhalt anzuzeigen. Das gilt auch, wenn du einen Navigationslink /apidocs auf deiner Wissensdatenbank hinzugefügt hast. Veröffentlichen Sie mindestens einen Endpunkt-Artikel, bevor Sie Ihre API-Referenz für Leser zugänglich machen.