OpenAPI-Referenz

Bereiche der Art API-Referenz erzeugen ihre Seiten automatisch aus einer OpenAPI-Spezifikation (Version 3.x, JSON oder YAML). Jeder Endpunkt bekommt eine eigene Seite mit Parametern, Request-Body, Antworten und einer „Try it“-Konsole, mit der Leser den Endpunkt direkt im Browser aufrufen können.

Einrichten#

1. Bereich anlegen#

   Neuer Bereich, Art API-Referenz wählen.

2. Spezifikation laden#

   In den Bereichseinstellungen im Abschnitt OpenAPI-Spezifikation eine der drei Möglichkeiten nutzen:

   • eine URL, unter der die Spezifikation liegt (z. B. https://api.example.com/openapi.json),
   • eine Datei hochladen (.json, .yaml, .yml),
   • den Inhalt in das Textfeld einfügen.

   Dann Laden (bzw. Aktualisieren) klicken. Docsello zeigt danach, wie viele Pfade geladen wurden und wann.

Was erzeugt wird#

• Eine Übersichtsseite mit Titel, Beschreibung, Version und Basis-URL aus info und servers.
• Pro Tag der Spezifikation eine Seite mit Beschreibung und den zugehörigen Endpunkten; Endpunkte ohne Tag landen unter „Endpoints“.
• Pro Endpunkt eine Seite, betitelt mit seiner summary.

Die Seiten laufen durch dieselbe Pipeline wie alle anderen: Sie sind durchsuchbar, erscheinen in der Navigation und in llms.txt und werden statisch ausgeliefert.

Aktuell halten aus der CI#

Lade die Spezifikation nach jedem Release per REST-API neu – die Referenz wird automatisch neu generiert:

curl -X PUT "$DOCSELLO_URL/api/v1/spaces/api-referenz/openapi" \
  -H "Authorization: Bearer $DOCSELLO_TOKEN" -H "content-type: application/json" \
  -d '{"url": "https://api.example.com/openapi.json"}'

Statt url kannst du mit text den Inhalt der Spezifikation direkt mitschicken.