DocfyUiModule.setup(mountPath, app, options?)
Sirve docfy-ui (la UI de documentación companion AI-first de este paquete) en mountPath, el mismo papel que cumplen SwaggerModule.setup() + swagger-ui-express para el Swagger UI puro.
Uso
Funciona tanto en apps Express (@nestjs/platform-express) como Fastify (@nestjs/platform-fastify). En Fastify, servir los assets estáticos necesita la peer dependency opcional @fastify/static (npm install @fastify/static), el mismo paquete del que depende @nestjs/swagger para su soporte de Swagger UI en 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: no hace falta ninguna configuración adicional, ya que docfy-ui obtiene /api-json same-origin por defecto.
Opciones
| Option | Type | Default | Description |
|---|---|---|---|
staticSpecPath | string | ninguno | Path to a pre-built OpenAPI JSON file, served at /api-json instead of the app's live one. |
specs | { name: string; url: string }[] | ninguno | 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 }[] } | ninguno | Enables the "Try it out" same-origin proxy — pass the same object you already have from SwaggerModule.createDocument(). See below. |
additionalProxyOrigins | string[] | ninguno | Extra origins the proxy is allowed to forward requests to, beyond what openApiDocument.servers declares. |
staticSpecPath (necesario bajo webpack: true, si no usas el plugin de CLI)
El pipeline de metadatos en runtime de DocfyModule no puede aplicar los docs files ahí, así que al /api-json en vivo le faltará todo lo que los docs files añadirían. Consulta El plugin de CLI para el fix recomendado y automático. Esta sección cubre la alternativa manual: generar de antemano un documento parcheado:
npx nestjs-docfy patch-spec --spec http://localhost:3000/api-json --out openapi.patched.jsonY sírvelo:
DocfyUiModule.setup('/docs', app, { staticSpecPath: './openapi.patched.json' });Llama a esto antes de SwaggerModule.setup(): Express resuelve las rutas en el orden de registro, así que el documento estático parcheado tiene prioridad sobre el en vivo para cualquier request a /api-json. En Fastify, que SwaggerModule.setup() registre su propia ruta /api-json junto a esto lanza FST_ERR_DUPLICATED_ROUTE al arrancar. Ahí el orden de registro no ayuda, así que apunta SwaggerModule.setup() a un jsonDocumentUrl distinto (o pasa { raw: false }) al combinarlo con staticSpecPath en Fastify.
Proxy same-origin
Habilita el proxy same-origin del "Try it out" de docfy-ui. Sin esto, la ejecución de requests hace un fetch directo del navegador a la API de destino, sujeto a la política CORS de esa API. Con esto, este módulo registra una ruta same-origin () y el navegador llama a esa en su lugar: el proxy hace la request real servidor a servidor, así que CORS nunca entra en juego. Pasa el mismo documento que ya tienes de 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 se construye solo a partir de URLs absolutas en el array servers[] del documento, más lo que haya en additionalProxyOrigins. Deliberadamente no hay fallback implícito de "mismo origen que esta request", ya que eso tendría que derivarse de un header Host controlado por el cliente, un vector clásico de SSRF. Una request a cualquier otro origen se rechaza con y un header de respuesta .
Cualquier otro fallo a nivel de proxy (destino inalcanzable, timeout, request malformada) también establece , para que docfy-ui pueda distinguir un fallo del proxy de una respuesta 4xx/5xx real de tu API. Esas pasan intactas, con su status/headers/body reales.