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.
Fassungen
Abschnitt betitelt „Fassungen“| 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.
Zusätzliche Felder in Antworten
Abschnitt betitelt „Zusätzliche Felder in Antworten“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.
Clients erzeugen
Abschnitt betitelt „Clients erzeugen“Das Dokument geht in jeden Generator, der OpenAPI 3.1 liest. Ein Beispiel mit dem OpenAPI Generator:
npx @openapitools/openapi-generator-cli generate \ -i https://docs.ski4.me/openapi.json \ -g typescript-fetch \ -o ./ski4me-clientFür TypeScript reichen oft schon die Typen:
npx openapi-typescript https://docs.ski4.me/openapi.json -o ./ski4me.d.tsFür einen Client, der immer zum Stand der Schnittstelle passt, nehmen Sie statt dieser Adresse die der Schnittstelle selbst.