DocfyUiModule.setup(mountPath, app, options?)
Serve docfy-ui (la UI di documentazione companion AI-first di questo pacchetto) su mountPath, lo stesso ruolo che SwaggerModule.setup() + swagger-ui-express svolgono per la Swagger UI grezza.
Utilizzo
Funziona sia su Express (@nestjs/platform-express) sia su Fastify (@nestjs/platform-fastify). Su Fastify, servire gli asset statici richiede la dipendenza peer opzionale @fastify/static (npm install @fastify/static), lo stesso pacchetto da cui dipende @nestjs/swagger per il supporto Swagger UI su Fastify.
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);Visita /docs: non serve altra configurazione, perché docfy-ui recupera /api-json di default dalla stessa origine.
Opzioni
| Option | Type | Default | Description |
|---|---|---|---|
staticSpecPath | string | nessuna | Path to a pre-built OpenAPI JSON file, served at /api-json instead of the app's live one. |
specs | { name: string; url: string }[] | nessuna | 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 }[] } | nessuna | Enables the "Try it out" same-origin proxy — pass the same object you already have from SwaggerModule.createDocument(). See below. |
additionalProxyOrigins | string[] | nessuna | Extra origins the proxy is allowed to forward requests to, beyond what openApiDocument.servers declares. |
staticSpecPath (necessario con webpack: true, se non usi il plugin CLI)
La pipeline di metadati a runtime di DocfyModule non può applicare i file docs in quel caso, quindi il /api-json live risulterà privo di tutto ciò che i file docs aggiungerebbero. Vedi Il plugin CLI per la soluzione automatica consigliata. Questa sezione copre l'alternativa manuale: generare in anticipo un documento già corretto:
npx nestjs-docfy patch-spec --spec http://localhost:3000/api-json --out openapi.patched.jsonE servilo:
DocfyUiModule.setup('/docs', app, { staticSpecPath: './openapi.patched.json' });Chiama questo prima di SwaggerModule.setup(): Express risolve le rotte nell'ordine di registrazione, quindi il documento statico corretto ha la precedenza su quello live per ogni richiesta a /api-json. Su Fastify, invece, se SwaggerModule.setup() registra la propria rotta /api-json insieme a questa, viene sollevato FST_ERR_DUPLICATED_ROUTE all'avvio. In quel caso l'ordine di registrazione non aiuta, quindi punta SwaggerModule.setup() verso un jsonDocumentUrl diverso (o passa { raw: false }) quando lo combini con staticSpecPath su Fastify.
Proxy same-origin
Abilita il proxy same-origin "Try it out" di docfy-ui. Senza di esso, l'esecuzione delle richieste è un fetch diretto dal browser verso l'API di destinazione, soggetto alla policy CORS di quell'API. Con questo attivo, il modulo registra una rotta same-origin () e il browser chiama quella al posto dell'altra: il proxy esegue la richiesta reale server-to-server, quindi CORS non si applica mai. Passa lo stesso documento che hai già da SwaggerModule.createDocument():
const document = SwaggerModule.createDocument(app, new DocumentBuilder().build());
SwaggerModule.setup('api', app, document);
DocfyUiModule.setup('/docs', app, { openApiDocument: document });La allowlist del proxy è costruita solo a partire dagli URL assoluti nell'array servers[] del documento, più qualunque voce in additionalProxyOrigins. Deliberatamente non esiste un fallback implicito "stessa origine di questa richiesta", perché andrebbe derivato da un header Host controllato dal client, un classico vettore SSRF. Una richiesta verso qualsiasi altra origine viene rifiutata con e un header di risposta .
Anche ogni altro fallimento a livello di proxy (target irraggiungibile, timeout, richiesta malformata) imposta , così docfy-ui può distinguere un fallimento del proxy da una vera risposta 4xx/5xx proveniente dalla tua API. Queste ultime passano intatte, con il loro status/header/body reali.