Verwaltung von API-Referenzen

Dieser Artikel behandelt alles, was Sie benötigen, um Ihre API in Document360 zu verwalten. Neue Referenzen erstellen, sie mit Ihrer Spezifikation synchronisieren und die verfügbaren Aktionen nutzen, um Ihre API-Dokumentation anzusehen, zu bearbeiten, zu veröffentlichen und zu organisieren.

API-Referenzliste

Die API-Referenzliste bietet Ihnen eine zentrale Ansicht aller konfigurierten API-Referenzen in Ihrem Arbeitsbereich. Um darauf zuzugreifen, gehen Sie in der linken Navigationsleiste zur API-Dokumentation ({ }) und klicken Sie im linken Navigationsbereich auf API-Referenzen .

Von hier aus können Sie den Namen, den Typ und das zuletzt aktualisierte Datum jeder Referenz sehen. Sie können auch eine neue API-Referenz erstellen, indem Sie oben rechts auf Neue API klicken.

Erstelle eine neue API-Referenz

Um eine neue API-Referenz zu erstellen, klicken Sie auf das Dropdown-Menü Erstellen in der oberen Navigationsleiste und wählen Sie Neue API. Dies öffnet das Referenzfenster Neue API, in dem Sie vier Optionen haben:

• API-Definition hochladen – Laden Sie eine JSON-, YAML- oder YML-Spezifikationsdatei direkt von Ihrem Gerät oder vom Document360-Laufwerk hoch.
• Erstellen Sie von einer URL – Rufen Sie Ihre Spezifikation automatisch von einer gehosteten URL ab.
• CI/CD-Fluss – Integrieren Sie sich in Ihre Pipeline, um die Dokumentation bei jeder Spezifikationsänderung automatisch zu aktualisieren. Erfordert Node.js.
• Probiere die Beispiel-Pet Store API-Datei aus – Nutze die Beispiel-Spezifikationsdatei von Document360, um den Arbeitsbereich zu erkunden, bevor du deine eigene hochlädst.

Definition der Upload-API

1. Wählen Sie den Funkknopf "API-Definition hochladen ".
2. Klicken Sie auf 'Von meinem Gerät hochladen ', um von Ihrem lokalen Speicher hochzuladen, oder auf 'Vom Laufwerk auswählen ', um eine Datei von Document360 Drive auszuwählen. Sie können Ihre Datei auch direkt in das Fenster ziehen und absetzen.
3. Document360 analysiert die Datei und generiert die API-Referenz. Wenn Warnungen erkannt werden, erweitern Sie den Abschnitt Warnungen und Warnungen , um sie zu überprüfen.
4. Klicken Sie auf Neue API-Referenz, um zum Veröffentlichungsbestätigungsfenster zu gelangen.

Erstellen aus URL

1. Wählen Sie die Schaltfläche "Aus URL erstellen " und klicken Sie auf Weiter.
2. Gib die URL ein, die auf deine OpenAPI-Spezifikationsdatei zeigt.
3. Klicken Sie auf Neue API-Referenz. Document360 holt und verarbeitet die Spezifikation.

CI/CD-Fluss

Der CI/CD-Fluss ermöglicht es Ihnen, Ihre API-Dokumentation automatisch mit Ihrer Spezifikation synchron zu halten. Anstatt bei jeder API-Änderung manuell eine neue Spezifikation hochzuladen, integrieren Sie die Document360-CLI in Ihre Pipeline, sodass die Dokumentation bei jeder Änderung automatisch aktualisiert wird.

Für vollständige Einrichtungsanweisungen siehe den Artikel zur CI/CD-Integration .

API-Referenzaktionen

Sobald eine API-Referenz erstellt wurde, klicken Sie auf das Mehr-(⋯)- Symbol daneben in der API-Referenzliste, um auf die folgenden Aktionen zuzugreifen:

Deine Dokumentation synchron halten

Wenn sich Ihre API ändert – neue Endpunkte hinzugefügt, Parameter aktualisiert, Antworten geändert, aber Sie müssen Ihre Dokumentation nicht manuell aktualisieren. Das Regenerieren Ihrer API-Referenz zieht automatisch alle Änderungen aus Ihrer Spezifikation ab.

Resync von einer bestehenden URL

1. In der API-Referenzliste klicken Sie auf das Mehr-(⋯)- Symbol neben der Referenz, die Sie aktualisieren möchten.
2. Klicken Sie auf Resync. Die Dokumentation regeneriert sich von der neuesten Version der Spezifikation unter der bestehenden URL.

Aktualisieren auf eine neue URL

1. Klicken Sie auf das Mehr- (⋯)- Symbol neben der Referenz.
2. Klicken Sie auf Bearbeiten.
3. Geben Sie die neue URL im URL-Feld ein.
4. Klicken Sie auf Aktualisieren.

Regenerieren aus einer Spezifikationsdatei

1. Klicken Sie auf das Mehr- (⋯)- Symbol neben der Referenz.
2. Klicken Sie auf Bearbeiten.
3. Laden Sie die neueste Spezifikationsdatei im JSON-, YAML- oder YML-Format hoch.
4. Klicken Sie auf Aktualisieren.

Resync über CI/CD

Wenn deine API-Referenz mit dem CI/CD-Flow eingerichtet wurde, erfolgt die Neusynchronisierung automatisch als Teil deiner Pipeline, sobald sich deine Spezifikation ändert. Du kannst auch eine manuelle Neusynchronisation mit dem apidocs:resync Befehl auslösen:

d360 apidocs:resync \
  --apiKey=YOUR_API_KEY \
  --userId=YOUR_USER_ID \
  --apiReferenceId=YOUR_API_REFERENCE_ID \
  --path=PATH_TO_SPEC_FILE

Für vollständige Details zur Einrichtung und Verwaltung des CI/CD-Flusses siehe den Artikel zur CI/CD-Integration .

Automatische vs. manuelle Neusynchronisation

Wenn du deine API-Dokumentation aus einer URL oder Datei generiert hast, wird sie nicht automatisch aktualisiert. Damit die Dokumentation automatisch aktualisiert wird, integriere dich mit dem CI/CD-Flow.

Verständnis der Endpunkt-Löschung während der Resynchronisierung

Wenn Sie Ihre API-Spezifikationsdatei aktualisieren, werden alle Endpunkte, die in der neuen Spezifikation nicht mehr vorhanden sind, dauerhaft gelöscht, zusammen mit allen benutzerdefinierten Inhalten, die diesen Endpunktseiten hinzugefügt werden.

Um Ihre Spezifikationsdatei sicher zu aktualisieren:

1. Lade die aktualisierte Spezifikationsdatei im Referenzfenster "API-Bearbeiten " hoch.
2. Wenn irgendwelche Endpunkte gelöscht werden, wird eine Warnung angezeigt. Klicken Sie auf 'Gelöschte Endpunkte anzeigen ', um die Liste der betroffenen Endpunkte einzusehen.
3. Wählen Sie das Kontrollkästchen "Fortsetzen bestätigen" aus, um die Löschung zu bestätigen.
4. Klicken Sie auf Aktualisieren , um fortzufahren.

Gelöschte Endpunkte werden in den Papierkorb verschoben, wo sie bis zu 30 Tage vorschauig angezeigt werden können, aber nicht wiederhergestellt werden können.

Dokumente im Entwurf führen

Nachdem du eine Spezifikation hochgeladen oder neu synchronisiert hast, kannst du die resultierende Dokumentation im Entwurfsmodus behalten, anstatt sie sofort zu veröffentlichen.

• Im Veröffentlichungsbestätigungsfenster klicken Sie auf Schließen statt Veröffentlichen. Alle generierten Artikel bleiben im Entwurfsmodus.
• Entwurfsartikel sind im Bereich Kategorien & Artikel im Portal sichtbar, aber für Leser auf der Knowledge Base-Seite nicht zugänglich.
• Sie können vor der Veröffentlichung eigene Inhalte zu Entwürfen überprüfen, bearbeiten und hinzufügen.

Verschachtelte Kategorien

Document360 unterstützt bis zu drei Ebenen von Unterkategorien im API-Dokumentationsarbeitsbereich. Kategorien werden basierend auf den Tag-Definitionen in Ihrer Spezifikationsdatei erstellt.

Um verschachtelte Kategorien zu erstellen, verwenden Sie das > Symbol in Ihren OpenAPI-Tags:

tags:
  - name: "Pets > Details"

Dadurch entsteht eine Pets Kategorie mit einer Unterkategorie Details darin. Diese Struktur bleibt während des Resynchronisations erhalten.

Kategorienordnung

Die Reihenfolge, in der Kategorien in deiner Dokumentation erscheinen, entspricht der in deiner Spezifikationsdatei definierten Tag-Reihenfolge. Um die Kategorienreihenfolge zu ändern, ordne das tags Array in deiner Spezifikation neu und synchronisiere dich neu.

Kategorieoptionen

Ein Rechtsklick auf eine Kategorie im Bereich Kategorien & Artikel erhält folgende Optionen:

Aktualisierung von spezifikationsgenerierten Inhalten über die API

Endpunktartikel, die aus einer API-Spezifikation (OpenAPI oder Swagger) generiert werden, sind über die Standard-Inhalts-API-Endpunkte schreibgeschützt und können auf diese Weise nicht abgerufen oder aktualisiert werden. Um diesen Inhaltstyp zu ändern:

1. Aktualisieren Sie Ihre API-Definitionsdatei (OpenAPI/Swagger).
2. Synchronisieren Sie die Dokumentation mit dem Portal, der CLI oder dem CI/CD-Fluss erneut, um die Änderungen widerzuspiegeln.

Dadurch bleibt der Inhalt deiner Endpunkt-Referenzen mit deiner API-Spezifikation konsistent.
Reguläre Knowledge Base-Artikel, wie Konzeptseiten, Authentifizierungsleitfäden oder andere nicht-spezifikationsbezogene Inhalte, sind nicht an die API-Spezifikation gebunden. Diese können wie andere Inhalte der Knowledge Base über die Standard-API-Endpunkte erstellt, aktualisiert und verwaltet werden.

Wenn Sie beim Versuch, Inhalte über die API zu aktualisieren, einen 403-Fehler erhalten, bestätigen Sie zuerst, mit welcher Art von Inhalten Sie arbeiten. Handelt es sich um spezifikationsgenerierte Inhalte, verwenden Sie den oben genannten Resync-Prozess, anstatt die Token-Berechtigungen anzupassen. Handelt es sich um einen Artikel ohne Spezifikation, siehe API-Tokens für Hinweise zur Überprüfung und Aktualisierung von Token-Berechtigungen.

FAQ

Hilfreiche Links

• d360 npm-Paket
• d360-Quellcode