Verwaltung von API-Referenzen

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

API-Referenzliste

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

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

Erstelle eine neue API-Referenz

Um eine neue API-Referenz zu erstellen, klicken Sie in der oberen Navigationsleiste auf das Dropdown-Menü Erstellen und wählen Sie Neue API. Dies öffnet das neue API-Referenzfenster, 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 es von Ihrem lokalen Speicher hochzuladen, oder auf 'Vom Laufwerk auswählen ', um eine Datei von Document360 Drive auszuwählen. Du kannst deine Datei auch direkt ins Fenster ziehen und abgeben.
3. Document360 analysiert die Datei und generiert die API-Referenz. Wenn Warnungen festgestellt 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 die Spezifikation ab und verarbeitet sie.

CI/CD-Fluss

Der CI/CD-Fluss ermöglicht es dir, deine API-Dokumentation automatisch mit deiner Spezifikation synchron zu halten. Anstatt bei jeder Änderung deiner API manuell eine neue Spezifikation hochzuladen, integrierst du die Document360-CLI in deine 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 deiner API-Referenz zieht automatisch alle Änderungen aus deiner 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. Klicke auf Resync. Die Dokumentation regeneriert sich von der neuesten Version der Spezifikation auf 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 Resynchronisierung 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 sich die Dokumentation automatisch aktualisiert, integrieren Sie sich in den CI/CD-Fluss.

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 Unterkategorieebenen im API-Dokumentationsarbeitsbereich. Kategorien werden basierend auf den Tag-Definitionen in deiner 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 Details Unterkategorie darin. Diese Struktur bleibt während der Resynchronisation erhalten.

Kategorienordnung

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

Kategorieoptionen

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

FAQ

Hilfreiche Links

• d360 npm-Paket
• d360-Quellcode