DocfyUiModule.setup(mountPath, app, options?)
Stellt docfy-ui (die AI-first-Begleitdokumentations-UI dieses Pakets) unter mountPath bereit – dieselbe Rolle, die SwaggerModule.setup() + swagger-ui-express für die reine Swagger UI übernehmen.
Verwendung
Funktioniert sowohl mit Express-Apps (@nestjs/platform-express) als auch mit Fastify (@nestjs/platform-fastify). Unter Fastify braucht das Ausliefern statischer Assets die optionale Peer-Dependency @fastify/static (npm install @fastify/static) – dasselbe Paket, auf das sich @nestjs/swagger selbst für die Swagger-UI-Unterstützung unter Fastify verlässt.
import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { DocfyUiModule } from 'nestjs-docfy';
const app = await NestFactory.create(AppModule);
DocfyUiModule.setup('/docs', app); // before SwaggerModule.setup; see staticSpecPath below
const document = SwaggerModule.createDocument(app, new DocumentBuilder().build());
SwaggerModule.setup('api', app, document); // exposes /api-json, which docfy-ui fetches by default
await app.listen(3000);Öffne /docs: Es ist keine weitere Konfiguration nötig, da docfy-ui standardmäßig same-origin /api-json abruft.
Optionen
| Option | Type | Default | Description |
|---|---|---|---|
staticSpecPath | string | keine | Path to a pre-built OpenAPI JSON file, served at /api-json instead of the app's live one. |
specs | { name: string; url: string }[] | keine | Extra OpenAPI specs to offer in docfy-ui's spec switcher, so one deployed instance can browse more than one service's documentation. |
openApiDocument | { servers?: { url: string }[] } | keine | Enables the "Try it out" same-origin proxy — pass the same object you already have from SwaggerModule.createDocument(). See below. |
additionalProxyOrigins | string[] | keine | Extra origins the proxy is allowed to forward requests to, beyond what openApiDocument.servers declares. |
staticSpecPath (nötig unter webpack: true, falls du das CLI-Plugin nicht nutzt)
Die Runtime-Metadaten-Pipeline von DocfyModule kann dort keine Docs-Dateien anwenden, deshalb fehlt im laufenden /api-json alles, was Docs-Dateien hinzufügen würden. Die empfohlene, automatische Lösung findest du unter Das CLI-Plugin. Dieser Abschnitt beschreibt die manuelle Alternative: erzeuge vorab ein gepatchtes Dokument:
npx nestjs-docfy patch-spec --spec http://localhost:3000/api-json --out openapi.patched.jsonUnd stelle es bereit:
DocfyUiModule.setup('/docs', app, { staticSpecPath: './openapi.patched.json' });Ruf das vor SwaggerModule.setup() auf: Express löst Routen in Registrierungsreihenfolge auf, also hat das gepatchte statische Dokument Vorrang vor dem laufenden für jede Anfrage an /api-json. Unter Fastify wirft SwaggerModule.setup(), wenn es daneben seine eigene /api-json-Route registriert, beim Start stattdessen FST_ERR_DUPLICATED_ROUTE. Die Registrierungsreihenfolge hilft hier nicht, also zeig mit SwaggerModule.setup() auf eine andere jsonDocumentUrl (oder übergib { raw: false }), wenn du es unter Fastify mit staticSpecPath kombinierst.
Same-Origin-Proxy
Aktiviert das Same-Origin-Proxy für „Try it out“ in docfy-ui. Ohne das führt die Ausführung einer Anfrage einen direkten Fetch vom Browser zur Ziel-API aus, unterliegt also deren eigener CORS-Richtlinie. Damit registriert dieses Modul eine Same-Origin-Route (), und der Browser ruft stattdessen diese auf: Das Proxy stellt die eigentliche Anfrage Server-zu-Server, sodass CORS nie greift. Übergib dasselbe Dokument, das du bereits von SwaggerModule.createDocument() hast:
const document = SwaggerModule.createDocument(app, new DocumentBuilder().build());
SwaggerModule.setup('api', app, document);
DocfyUiModule.setup('/docs', app, { openApiDocument: document });Die Allowlist des Proxys wird ausschließlich aus absoluten URLs im servers[]-Array des Dokuments gebaut, plus allem in additionalProxyOrigins. Es gibt bewusst keinen impliziten „gleicher Origin wie diese Anfrage“-Fallback, da der sich aus einem client-kontrollierten Host-Header ableiten müsste – ein klassischer SSRF-Vektor. Eine Anfrage an jeden anderen Origin wird mit und einem -Response-Header abgelehnt.
Jeder andere Fehler auf Proxy-Ebene (Ziel nicht erreichbar, Timeout, fehlerhafte Anfrage) setzt ebenfalls , sodass docfy-ui einen Proxy-Fehler von einer echten 4xx/5xx-Antwort deiner API unterscheiden kann. Diese werden unverändert durchgereicht, mit ihrem echten Status, Headern und Body.