Der Try-it-Client
Eine echte Anfrage, gesendet vom Browser des Lesers.
Jede Operationsseite trägt einen Client: Server wählen, Parameter füllen, Body bearbeiten, senden.
Niemals ein Proxy
Die Anfrage stellt der Browser des Lesers mit fetch, direkt an den Server, den
er gewählt hat. Nichts läuft über die Site, die die Dokumentation ausliefert.
Das ist eine Entscheidung, keine Einschränkung. Ein Proxy hieße, dass die Zugangsdaten des Lesers zu einem Dritten reisen — und die Doku-Site ist ein Dritter für die API, die sie dokumentiert. Der Preis ist, dass eine API ohne CORS von hier nicht aufgerufen werden kann; der Client sagt das, statt still zu scheitern.
Server
Jeder Server, den das Dokument deklariert, mit seinen Variablen als Felder. Eine
Operation, die servers überschreibt, bekommt ihre eigene Liste.
Authentifizierung
Ein Feld pro Scheme, das die Anforderung der Operation nennt.
| Scheme | Was der Client tut |
|---|---|
apiKey in Header oder Query | Sendet den Wert dorthin, wo das Dokument es sagt |
http bearer | Fragt nach dem Token, sendet Authorization: Bearer … |
http basic | Fragt nach Benutzer und Passwort, kodiert beide |
oauth2, openIdConnect | Fragt nach dem Token — beide enden in einem Bearer-Header |
apiKey im Cookie | Sagt, dass es nicht geht. Eine Seite darf kein Cookie setzen |
mutualTLS | Sagt, dass es nicht geht. Eine Seite hat kein Client-Zertifikat |
!IMPORTANT Was du in ein Authentifizierungsfeld tippst, bleibt in diesem Tab, wird nie gespeichert und geht nur an den Server, den du gewählt hast.
Ein Cookie-Parameter wird bewusst nicht in die Anfrage gebaut. Cookie ist
für fetch ein verbotener Header-Name: Ein Browser verwirft ihn ohne Fehler und
ohne Konsolenausgabe, die Anfrage hätte also still die Zugangsdaten nicht
enthalten, während das curl-Sample daneben den Header gezeigt hätte — die eine
Stelle, an der ein Leser nachsieht. Der Client sagt stattdessen, dass das Cookie
von einer Seite aus nicht gesetzt werden kann, damit das Gesendete und das
Gezeigte wieder dieselbe Anfrage sind.
Ein Wert zum Anfangen
Ein Schema darf einen nennen, und der Client füllt das Feld damit:
securitySchemes:
bearer:
type: http
scheme: bearer
x-duxt-example: demo-token
Eine Erweiterung, weil OpenAPI kein Feld dafür hat: Ein Security-Schema sagt, wo ein Credential hingeht, nie wie eines aussieht. Es ist der Unterschied zwischen einen Client sehen und ihn arbeiten sehen — ein Demo-Endpunkt, der jedes Token akzeptiert, kann das sagen, statt erst einen Wert erfinden zu lassen.
!CAUTION Eine veröffentlichte Datei. Hier gehört ein Demo-Wert hin, nie ein echtes Credential.
Der Body
Zwei Ansichten desselben Werts, und der Leser wählt einmal für die ganze Site:
- Formular — ein Feld pro Property, aus dem Schema gezeichnet, mit den Constraints, die es deklariert.
- JSON — ein Editor, für einen Body, den das Formular nicht zeichnen kann. Ein Body, der noch kein gültiges JSON ist, wird wie geschrieben gesendet statt blockiert.
Ein Schema, das zu lose ist, um es als Formular zu zeichnen, sagt das und bietet den Editor an.
Der Editor ist CodeMirror, auf Abruf geladen — eine Seite ohne Endpoint lädt nichts davon. Er ist bewusst nicht Monaco: Ein Editor, dessen Worker und Megabyte jede konsumierende Site mitträgt, für ein Feld mit zehn Zeilen JSON, ist der falsche Handel für ein Paket.
Die Antwort
Status, Header und Body, unter dem Editor. Das ist auch der Grund, warum die Code-Samples daneben bei der Anfrage aufhören — siehe Request-Samples.
Wenn sie nicht ankommt
fetch scheitert mit einem nackten TypeError bei einer CORS-Ablehnung, einem
DNS-Fehler und einem fehlenden Netz gleichermaßen — der Client kann dem Leser
also nicht sagen, welches der drei es war. Er sagt, dass die Anfrage den Server
nicht erreicht hat, und nennt die beiden wahrscheinlichen Gründe, statt einen zu
raten.