不只是一份
Swagger 文档。

nestjs-docfy 通过 companion 文件命名约定，把 Swagger/OpenAPI 文档从控制器逻辑中分离出来，方式和 Nest 已经在用的 *.controller.spec.ts.

Installation

npm install nestjs-docfy
# peer deps
npm install @nestjs/common @nestjs/swagger reflect-metadata

最新版本 v0.18.1许可证 MIT

约定优于配置的 companion 文件

users.controller.ts → users.controller.docs.ts。和 Nest 已经在用的 *.controller.spec.ts 是同一套模式。

带 CI 门禁的 CLI

check、coverage --min、lint 和 patch-spec。文档缺失时直接让构建失败。

自动类型推断

接口、class-validator 和 @HttpCode() 无需额外装饰器即可变成 OpenAPI schema。

AI 优先的 Docfy UI

每个端点都带 Copy for AI 按钮的参考界面，特别适合粘贴进 LLM。

docfy-ui：AI 优先的参考查看器

nestjs-docfy 组装出的 OpenAPI spec，同样也是 docfy-ui 渲染的内容，不需要额外配置，用的是同一份事实来源。

Copy for AI：一份确定性生成、可直接喂给 LLM 的端点摘要，而不是带 $ref 的原始 JSON 转储
⌘K 即时搜索所有端点
每个端点完整的请求/响应细节，直接从 spec 生成

docfy-ui detalhe de endpoint com Copy for AI

为 AI 智能体打造，而不仅仅是给人看的

docfy-mcp 将你的 OpenAPI 规范以 MCP 工具的形式暴露出来，这样 Claude、Cursor 或任何兼容 MCP 的智能体都能直接查询你的 API，不用再把 JSON 粘贴进提示词里。

list_endpoints / get_endpoint：浏览并检查任意操作，格式与 docfy-ui 渲染的标准化结构一致
lint_spec：在上线前标记出缺失的摘要、描述、标签和错误响应
diff_specs：比较两个 OpenAPI 文档，标记出破坏性变更与信息性变更
contract_test：直接从智能体自身的工具调用中，将实时响应与声明的 schema 进行校验
对正在运行的 NestJS 服务器零配置接入，或指向一个静态 spec 文件

claude_desktop_config.json

{
  "mcpServers": {
    "docfy": {
      "command": "npx",
      "args": ["-y", "docfy-mcp", "--url", "http://localhost:3000/docs-json"]
    }
  }
}

了解 docfy-mcp

实际用起来是什么样

之前：一个被装饰器淹没的控制器。之后：只剩路由本身，文档就在旁边的 companion 文件里。

users.controller.ts

@WithDocs()
@Controller('users')
export class UsersController {
  constructor(private readonly users: UsersService) {}

  @Get(':id')
  findOne(@Param('id') id: string) {
    return this.users.findOne(id);
  }
}

users.controller.docs.ts

import { docs } from 'nestjs-docfy';
import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';
import { UsersController } from './users.controller';

docs(UsersController, {
  classDecorators: [ApiTags('users')],
  methods: {
    findOne: [
      ApiOperation({ summary: 'Get user by id' }),
      ApiResponse({ status: 200, description: 'OK', type: UserDto }),
      ApiResponse({ status: 404, description: 'User not found' }),
    ],
  },
});

只在启动时运行，零请求时开销和内联装饰器生成完全相同的 OpenAPI 输出Companion 文件约定，就像 *.spec.ts 一样

没有猴子补丁，没有运行时代理

只是恰到好处的时机，加上 Reflect 元数据。

写 companion 文件

users.controller.docs.ts 调用 docs(UsersController, { ... })，普通的 Swagger 装饰器，只是搬到了另一个文件里。

启动时被发现

DocfyModule.forRoot() 通过命名约定找到它，并在 SwaggerModule.createDocument() 运行之前，把 Reflect 元数据写到控制器的方法上。

完全一致的 OpenAPI 输出

SwaggerModule 看到的元数据，和装饰器直接写在控制器上时完全一样。

不只是一个 Swagger 插件，而是完整的工具链。

大多数工具只做到装饰器这一步。nestjs-docfy 还提供了 CLI、查看器和 AI 集成，团队要让文档保持真实可靠，靠的就是这些。

一套能守住 CI 的 CLI

generate、check、coverage --min、lint 和 patch-spec 会在文档与代码出现偏差的那一刻就让构建失败，不用等到几个月后才发现。

如果你愿意，运行时成本可以为零

webpack CLI 插件在构建时计算好一切；生产环境中不会有任何按请求执行的逻辑。

docfy-ui 内置，无需单独购买

库中已包含完整的 AI-first 参考查看器，不需要额外账号，也没有单独的付费方案。

让智能体成为一等公民

docfy-mcp 把同一份规范暴露给 Claude、Cursor 以及任何 MCP 客户端，让你的 API 可以被查询，不只是被阅读。

适配你现有的任意 NestJS 项目结构

简单项目、Nx 工作区和 Nest CLI monorepo 都会被自动识别，不需要手写任何配置文件。

一条命令从零到完全接入

nestjs-docfy init 一次性完成模块接入、为所有控制器添加装饰器、并生成文档。

查看完整文档

不只是一份Swagger 文档。