# OpenAPI-Referenz

> Aus einer OpenAPI-Spezifikation eine API-Referenz mit Endpunkt-Seiten und „Try it“-Konsole erzeugen.

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

:::steps
### Bereich anlegen

**Neuer Bereich**, Art **API-Referenz** wählen.

### 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](doc:rest-api) neu – die Referenz wird automatisch neu
generiert:

```bash
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.

:::info[Die Docsello-API selbst]
Die Spezifikation der Docsello-API liegt unter `/api/v1/openapi.json` deiner Installation – ein guter Kandidat für
einen eigenen API-Referenz-Bereich.
:::