Try it out

Führe eine echte Anfrage aus dem Browser aus, direkt von der Seite eines Endpunkts, mit Auth-Unterstützung und einem Same-Origin-Proxy, um CORS zu vermeiden.

Verwendung

Jedes Request-Panel eines Endpunkts hat neben den Sprach-Tabs einen Code/Try-it-out-Umschalter. Try it out ist ein editierbares Formular (Base URL, Path-/Query-/Header-Parameter, Request Body), das über executeRequest() eine echte Anfrage ausführt und das Ergebnis in einem Live-Tab neben den deklarierten Beispielantworten zeigt (hübsch formatiert, wenn der Body JSON ist, mit einer freundlichen Meldung statt eines rohen Fehlers bei Netzwerk-/CORS-Problemen). Die Base URL ist standardmäßig der erste Eintrag im servers[]-Array des OpenAPI-Dokuments, falls vorhanden, und immer frei editierbar.

Authentifizierung

Endpunkte mit einer security-Anforderung bekommen ein inline Auth-Formular, ein Eingabefeld pro deklariertem Schema:

  • apiKey: geht an einen Header oder Query-Parameter, je nach deklariertem Ort.
  • http bearer / OAuth2 / OpenID Connect: akzeptieren alle ein Token, das du direkt einfügst; es wird kein OAuth-Flow durchgeführt.
  • http basic: erwartet user:pass.

Credentials sind global (geteilt über jeden Endpunkt, der dasselbe Schema nutzt, wie ein echtes Dev-Token es wäre) und bleiben in localStorage erhalten, damit sie einen Reload überstehen.

Wenn eine erfolgreiche Live-Antwort ein Feld enthält, das wie ein Token aussieht (z. B. access_token eines Login-Endpunkts, auch verschachtelt unter einer Hülle wie data.access_token), lässt dich ein Button „Als … Token verwenden“ es für den Rest der Session als Credential wiederverwenden, ohne manuelles Kopieren.

Same-Origin-Proxy

Standardmäßig ist Try it out ein direkter fetch() vom Browser zur Ziel-API, unterliegt also deren eigener CORS-Richtlinie. Wird nestjs-docfys DocfyUiModule.setup() (siehe API-Referenz) mit einem OpenAPI-Dokument konfiguriert, erkennt docfy-ui das injizierte globale window.__DOCFY_PROXY_PATH__ und leitet die Anfrage stattdessen über ein Same-Origin-Server-Proxy, sodass CORS nie greift.

Die Allowlist des Proxys wird ausschließlich aus absoluten URLs im servers[]-Array des Dokuments gebaut. Es gibt keinen impliziten „gleicher Origin wie diese Anfrage“-Fallback, da der von client-kontrollierten Headern abhängen würde. Eine Anfrage an einen nicht erlaubten Origin, oder jeder andere Fehler am Proxy selbst, kommt mit einem X-Docfy-Proxy-Error-Response-Header zurück, sodass docfy-ui einen Proxy-Fehler von einer echten Antwort deiner API unterscheiden kann.