Konfiguration
Die UI hat keine Build-Zeit-Konfiguration: Sie löst die anzuzeigende Spec vollständig zur Laufzeit auf, nach einer Regel mit einem Override.
Eine Regel, ein Override
| Source | When | Example |
|---|---|---|
GET /api-json | Standard: entspricht dem, was SwaggerModule.setup() aus @nestjs/swagger neben der Swagger UI bereitstellt | https://api.example.com/docs → fetches https://api.example.com/api-json |
?spec=<url> | Query-Parameter: hat Vorrang vor dem Standard, wenn vorhanden | https://docs.example.com/?spec=https://api.example.com/api-json |
CORS über verschiedene Origins
Wird die UI auf einem anderen Origin als die API ausgeliefert, nutze den ?spec=-Override und stell sicher, dass die CORS-Konfiguration der API diesem Origin GET auf das JSON-Dokument erlaubt.
Diese Same-Origin-Frage kommt bei der Ausführung von Requests erneut auf: siehe Try it out, wie dessen Proxy CORS komplett umgeht, ohne die eigene Konfiguration der API anzufassen.
Mehrere Specs
Übergib specs an DocfyUiModule.setup(), damit Nutzer zwischen mehreren OpenAPI-Dokumenten wechseln können, ohne die UI zu verlassen – nützlich, wenn eine docfy-ui-Instanz mehrere Services abdecken soll:
DocfyUiModule.setup('/docs', app, {
specs: [
{ name: 'Users service', url: 'https://users.example.com/api-json' },
{ name: 'Orders service', url: 'https://orders.example.com/api-json' },
],
});Jede url wird clientseitig genauso abgerufen wie die Standard-/api-json-Spec (same-origin oder nicht, entsprechend der CORS-Richtlinie dieses Origins). Ein Dropdown erscheint in der Sidebar nur, wenn zwei oder mehr Specs konfiguriert sind. Lässt du specs ganz weg, verhält sich docfy-ui genau wie vorher, kein Umschalter wird gerendert.