Zum Inhalt springen

Werkzeuge

OpenAPI-Dokument

Die offene Schnittstelle ist in OpenAPI 3.1 beschrieben. Aus dem Dokument lassen sich Clients erzeugen, Anfragen prüfen und Werkzeuge wie Swagger oder Postman füttern.

Adresse Braucht
von der Schnittstelle selbst https://skirent.sumware.at/api/ext/openapi.json keinen Schlüssel
von dieser Seite, mit Beispielen https://docs.ski4.me/openapi.json nichts

Die Schnittstelle erzeugt ihre Beschreibung aus derselben Tabelle im Code, aus der auch die Routen entstehen. Die Anfrageseite kommt aus den Regeln, die jeder Endpunkt prüft; die Antwortseite prüft ein Test gegen jede echte Antwort. Eine Beschreibung, die neben dem Code gepflegt wird, läuft auseinander. Diese nicht.

Die Fassung dieser Seite ist dieselbe Beschreibung, Stand skirent@6dfd7c5, ergänzt um:

  • zu jedem Endpunkt ein Beispiel für Anfrage und Antwort aus dem Mitschnitt,
  • Beispiele für die Fehler 401, 404 und 429,
  • den Verweis auf die Seite, die den Endpunkt erklärt.

Pfade, Felder und Rechte sind unverändert.

Teil Inhalt
paths jeder Endpunkt mit Parametern, Rumpf und Antworten
components.securitySchemes.apiKey die Anmeldung als Bearer, mit der Liste der wählbaren Rechte
components.schemas.Error die Fehlerhülle
x-required-permission je Endpunkt das Recht, das der Schlüssel braucht
tags die sieben Bereiche: Schlüssel, Buchungen, Tour, Unterkünfte, Einstellungen, Preise, Kurse

x-required-permission ist eine eigene Erweiterung. Ein erzeugter Client kann daran vor dem Aufruf prüfen, ob der Schlüssel das Recht trägt, das whoami genannt hat.

Die Schemata der Antworten erlauben zusätzliche Felder. So legt es die Versionierung fest: ein Feld kann dazukommen, keines verschwindet. Stellen Sie einen erzeugten Client so ein, dass er unbekannte Felder überliest statt abzubrechen.

Das Dokument geht in jeden Generator, der OpenAPI 3.1 liest. Ein Beispiel mit dem OpenAPI Generator:

Terminal-Fenster
npx @openapitools/openapi-generator-cli generate \
-i https://docs.ski4.me/openapi.json \
-g typescript-fetch \
-o ./ski4me-client

Für TypeScript reichen oft schon die Typen:

Terminal-Fenster
npx openapi-typescript https://docs.ski4.me/openapi.json -o ./ski4me.d.ts

Für einen Client, der immer zum Stand der Schnittstelle passt, nehmen Sie statt dieser Adresse die der Schnittstelle selbst.