DocfyUiModule.setup(mountPath, app, options?)
Serveert docfy-ui (de AI-first companion-documentatie-UI van dit pakket) op mountPath, dezelfde rol die SwaggerModule.setup() + swagger-ui-express spelen voor de kale Swagger UI.
Gebruik
Werkt op zowel Express- (@nestjs/platform-express) als Fastify-apps (@nestjs/platform-fastify). Op Fastify heeft het serveren van statische assets de optionele peer dependency @fastify/static nodig (npm install @fastify/static), hetzelfde pakket waar @nestjs/swagger zelf op leunt voor Fastify Swagger UI-ondersteuning.
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);Ga naar /docs: er is geen verdere configuratie nodig, want docfy-ui haalt /api-json standaard same-origin op.
Opties
| Option | Type | Default | Description |
|---|---|---|---|
staticSpecPath | string | geen | Path to a pre-built OpenAPI JSON file, served at /api-json instead of the app's live one. |
specs | { name: string; url: string }[] | geen | 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 }[] } | geen | Enables the "Try it out" same-origin proxy — pass the same object you already have from SwaggerModule.createDocument(). See below. |
additionalProxyOrigins | string[] | geen | Extra origins the proxy is allowed to forward requests to, beyond what openApiDocument.servers declares. |
guides | { slug, title, content }[] | geen | Narrative markdown pages at /guides/:slug, listed in the sidebar. A guide can embed a live, runnable request via a docfy-try fenced block (single line METHOD /path matching an endpoint in the current spec) — renders the endpoint's real request panel inline instead of just linking to its page. |
staticSpecPath (nodig onder webpack: true, als je de CLI-plugin niet gebruikt)
De runtime-metadatapijplijn van DocfyModule kan daar geen docsbestanden toepassen, dus zal de live /api-json alles missen wat docsbestanden zouden toevoegen. Zie De CLI-plugin voor de aanbevolen, automatische fix. Deze sectie behandelt het handmatige alternatief: genereer van tevoren een gepatcht document:
npx nestjs-docfy patch-spec --spec http://localhost:3000/api-json --out openapi.patched.jsonEn serveer het:
DocfyUiModule.setup('/docs', app, { staticSpecPath: './openapi.patched.json' });Roep dit vóór SwaggerModule.setup() aan: Express lost routes op in registratievolgorde, dus krijgt het gepatchte statische document voorrang op het live document voor elke request naar /api-json. Op Fastify gooit SwaggerModule.setup(), dat daarnaast zijn eigen /api-json-route registreert, in plaats daarvan FST_ERR_DUPLICATED_ROUTE op bij het opstarten. Registratievolgorde helpt daar niet, dus wijs SwaggerModule.setup() naar een andere jsonDocumentUrl (of geef { raw: false } mee) wanneer je dit combineert met staticSpecPath op Fastify.
Same-origin proxy
Zet de same-origin "Try it out"-proxy van docfy-ui aan. Zonder deze doet het uitvoeren van een request een directe fetch vanuit de browser naar de doel-API, onderworpen aan het eigen CORS-beleid van die API. Mét deze registreert deze module een same-origin route () en roept de browser die aan in plaats daarvan: de proxy voert het echte verzoek server-naar-server uit, dus CORS speelt nooit een rol. Geef hetzelfde document mee dat je al hebt van SwaggerModule.createDocument():
const document = SwaggerModule.createDocument(app, new DocumentBuilder().build());
SwaggerModule.setup('api', app, document);
DocfyUiModule.setup('/docs', app, { openApiDocument: document });De allowlist van de proxy wordt alleen opgebouwd uit absolute URL's in de servers[]-array van het document, plus alles in additionalProxyOrigins. Er is bewust geen impliciete "zelfde origin als deze request"-fallback, omdat die afgeleid zou moeten worden van een door de client bepaalde Host-header, een klassieke SSRF-vector. Een verzoek voor een andere origin wordt geweigerd met en een -responseheader.
Elke andere fout op proxy-niveau (doel onbereikbaar, timeout, misvormd verzoek) zet ook , zodat docfy-ui een proxyfout kan onderscheiden van een echte 4xx/5xx-response van je eigen API. Die laatste komen ongemoeid door, met hun echte status/headers/body.