DocfyUiModule.setup(mountPath, app, options?)

在 mountPath 上提供 docfy-ui（这个包的 AI 优先配套文档界面），扮演的角色和 SwaggerModule.setup() + swagger-ui-express 对原生 Swagger UI 的作用一样。

用法

同时适用于 Express（@nestjs/platform-express）和 Fastify（@nestjs/platform-fastify）应用。在 Fastify 上，静态资源服务需要可选的对等依赖 @fastify/static（npm install @fastify/static），这也是 @nestjs/swagger 自身在 Fastify 上支持 Swagger UI 所依赖的同一个包。

ts
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);

访问 /docs：不需要任何额外配置，因为 docfy-ui 默认会同源请求 /api-json。

选项

OptionTypeDefaultDescription
staticSpecPathstring无Path to a pre-built OpenAPI JSON file, served at /api-json instead of the app's live one.
specs{ name: string; url: string }[]无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 }[] }无Enables the "Try it out" same-origin proxy — pass the same object you already have from SwaggerModule.createDocument(). See below.
additionalProxyOriginsstring[]无Extra origins the proxy is allowed to forward requests to, beyond what openApiDocument.servers declares.
guides{ slug, title, content }[]无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（在 webpack: true 且未使用 CLI 插件时需要）

DocfyModule 的运行时元数据管线在这种情况下无法生效，实时的 /api-json 会缺失所有 docs 文件本该添加的内容。推荐的自动修复方式见 CLI 插件。这一节说明手动的替代方案：预先生成一份打过补丁的文档：

bash
npx nestjs-docfy patch-spec --spec http://localhost:3000/api-json --out openapi.patched.json

然后提供它：

ts
DocfyUiModule.setup('/docs', app, { staticSpecPath: './openapi.patched.json' });

把这一步放在 SwaggerModule.setup() 之前 调用：Express 按注册顺序解析路由，所以对 /api-json 的任何请求，静态的补丁文档都会优先于实时文档生效。而在 Fastify 上，SwaggerModule.setup() 再注册一次自己的 /api-json 路由会直接在启动时抛出 FST_ERR_DUPLICATED_ROUTE。注册顺序在这里帮不上忙，所以在 Fastify 上把 staticSpecPath 和它结合使用时，需要让 SwaggerModule.setup() 指向另一个 jsonDocumentUrl（或者传入 { raw: false }）。

同源代理

启用 docfy-ui 的“Try it out”同源代理。不启用它的话，请求会由浏览器直接发往目标 API，受限于该 API 自身的 CORS 策略。启用后，这个模块会注册一个同源路由（），浏览器改为调用它：代理会以服务器到服务器的方式发出真实请求，CORS 就完全不适用了。把你已经从 SwaggerModule.createDocument() 拿到的同一份文档传进去：

ts
const document = SwaggerModule.createDocument(app, new DocumentBuilder().build());
SwaggerModule.setup('api', app, document);
DocfyUiModule.setup('/docs', app, { openApiDocument: document });

代理的允许列表只根据文档 servers[] 数组中的绝对 URL 构建，再加上 additionalProxyOrigins 里的内容。这里刻意没有隐式的“和本次请求同源”兜底，因为那必须依赖客户端可控的 Host 请求头，是经典的 SSRF 攻击面。对其他来源的请求会被拒绝，返回 并带上 响应头。

代理层其他任何失败（目标不可达、超时、请求格式错误）也都会设置 ，这样 docfy-ui 就能把代理失败和你的 API 真正返回的 4xx/5xx 区分开。真实响应会原样透传，状态码、响应头、响应体都不受影响。