NocoBase API 文档插件（api-doc）使用指南：基于 Swagger/OpenAPI 的接口文档生成与插件接入

NocoBase API 文档插件（api-doc）使用指南：基于 Swagger/OpenAPI 的接口文档生成与插件接入

【免费下载链接】nocobaseNocoBase is an open-source AI + no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase

NocoBase 通过内置的 api-doc 插件，基于 Swagger（OpenAPI）规范自动生成并托管整个系统的 HTTP API 文档。本文围绕该插件，讲解文档页面的访问方式、/api/swagger:get六大文档入口（总文档 / 内核 / 插件 / collections）的用法，并结合插件源码剖析文档聚合机制，最后给出为自定义插件编写 Swagger 文档的完整步骤与配置示例。

介绍

NocoBase 是开源的 AI + 无代码业务系统构建平台，所有数据操作（数据表 CRUD、关联资源、用户鉴权、工作流触发等）最终都暴露为 HTTP API。为了让开发者快速了解、调试这些接口，NocoBase 内置了api-doc 插件，它基于 Swagger（OpenAPI）规范自动生成一份随系统实时更新的 API 文档，并以可视化页面 + JSON 数据两种形态提供。

该插件的实现位于仓库 packages/plugins/@nocobase/plugin-api-doc，其核心职责：

• 聚合三类 Swagger 文档来源：内核（@nocobase/server）自带文档、所有已启用插件的自定义文档、用户自定义 collections 动态生成的文档；
• 对外暴露swagger单例资源（/api/swagger:get），按ns参数返回不同维度的 OpenAPI JSON；
• 在管理后台提供可视化的文档预览页面。

安装与激活

api-doc 是 NocoBase 的内置插件，随应用一起分发，无需单独安装。安装 NocoBase 后，在插件管理页面找到 api-doc 并激活即可使用。

激活后，插件会在服务端加载阶段注册资源与权限，相关逻辑见 server.ts：

• 通过this.app.resourcer.define定义名为swagger的single类型资源，仅开放get、getUrls两个 action；
• 通过this.app.acl.allow('swagger', ['get', 'getUrls'], 'loggedIn')设置访问权限：登录用户即可访问；
• 同时注册了权限片段pm.api-doc.documentation，对应swagger:*操作，便于在角色权限中精确控制。

访问 API 文档页面

激活插件后，在浏览器中访问管理后台的文档页面：

http://localhost:13000/admin/settings/api-doc/documentation

其中13000为 NocoBase 默认应用端口（按实际部署环境调整）。页面由客户端侧 client-v2 目录下的Documentation.tsx、DocumentationContent.tsx等组件渲染，通过swagger:getUrls拉取文档入口列表，再按所选入口加载对应 OpenAPI JSON，并以内嵌的 Swagger UI 呈现。

文档概览：六大文档入口

文档页面按命名空间（ns）维度组织为六类入口，全部通过/api/swagger:get获取 JSON，页面 UI 上会自动列出这些入口供切换：

其中ns参数的解析逻辑见 server.ts：ns按/分割，ns=plugins/xxx中第一段plugins决定文档类型，剩余部分xxx作为插件名传入；core、collections同理。

内核文档（ns=core）

ns=core返回 NocoBase 内核自带接口的 Swagger JSON。从源码 loader.ts 看，内核通过loadSwagger('@nocobase/server')加载：

export const loadSwagger = (packageName: string) => { const prefixes = ['src', 'lib', 'dist']; const targets = ['swagger.json', 'swagger/index.json', 'swagger']; for (const prefix of prefixes) { for (const dict of targets) { try { const file = `${packageName}/${prefix}/${dict}`; const filePath = require.resolve(file); delete require.cache[filePath]; return requireModule(file); } catch (error) { // } } } return {}; };

即按src→lib→dist前缀、swagger.json→swagger/index.json→swagger（目录）的顺序依次解析，命中即返回。这也解释了为何插件文档文件放置在包内的swagger目录下即可被自动识别。

插件文档（ns=plugins）

ns=plugins返回所有已启用插件 Swagger 文档的合并结果。其数据来源是数据库中的applicationPlugins表（见 loader.ts）：

const plugins = await db.getRepository('applicationPlugins').find({ filter: { enabled: true, ...nameFilter }, });

只有enabled: true的插件才会被纳入；每个插件取其packageName，调用loadSwagger(packageName)加载文档，再按插件名聚合。因此：

• 插件未启用时，其文档不会出现在聚合结果中；
• 指定ns=plugins/{name}时，会按插件名过滤，只返回该插件的文档（若该插件没有自定义 Swagger 文件则返回空对象）。

collections 文档（ns=collections）

ns=collections返回用户自定义数据表（collections）的接口文档，它不是读静态文件，而是由 collections/index.ts 动态生成：

• 遍历collections表中name不为roles、users且hidden为假的数据表（见 swagger/index.ts）；
• 对每个 collection 调用collection2Swagger(collectionName, withAssociation)，将数据表的字段类型映射为 OpenAPI Schema，并生成标准的 CRUD 路径（list、get、create、update、destroy等）；
• 字段类型映射关系集中定义在 constants.ts 与 collections/components/field-type-map.ts。

指定ns=collections/{name}时，只生成指定 collection 及其关联资源的文档。关联资源路径（如posts.user）的生成逻辑位于 collections/paths/associations，其中single-association.ts（belongsTo / hasOne 等单记录关联）与multiple-association.ts（hasMany / belongsToMany 等多记录关联）分别处理不同类型。

聚合机制：文档如何合并

总文档/api/swagger:get的生成过程（见 swagger/index.ts）：

async generateSwagger(options: { plugins?: string[] } = {}) { const base = await this.getBaseSwagger(); const core = options.plugins ? {} : await loadSwagger('@nocobase/server'); const plugins = await this.loadSwaggers(options.plugins); return merge(merge(core, plugins), base); }

合并顺序为：内核文档 → 插件文档 → 基础文档（base），后合并的会覆盖同路径/同 schema 的冲突项。基础文档由 base-swagger.ts 提供（包含 OpenAPI 版本、服务信息、通用安全定义等）。深层合并逻辑实现在 merge.ts，可对paths、components.schemas、components.parameters等按对象键递归合并。

此外，资源还提供了swagger:getUrls（对应/api/swagger:getUrls）用于一次性获取全部文档入口列表，供文档页面侧边栏渲染使用。

开发指南：为插件编写 Swagger 文档

1. 创建 swagger 文件

在插件src目录下新建swagger/index.ts，导出默认配置对象：

export default { info: { title: 'NocoBase API - Auth plugin', }, tags: [], paths: {}, components: { schemas: {}, }, };

该对象即 OpenAPI 文档片段，加载器会在src/swagger、lib/swagger、dist/swagger目录下自动寻找（对应 loader.ts 的查找顺序），因此无需任何注册代码，插件启用后文档即自动纳入聚合。

2. 编写 OpenAPI 片段

在paths中描述接口，在components.schemas中定义数据模型。以下以 api-doc 插件自身文档为例（见 swagger.ts）：

export default { info: { title: 'NocoBase API - API doc plugin', }, paths: { '/swagger:getUrls': { get: { description: 'Get all api-doc destination', tags: ['swagger'], responses: { 200: { description: 'successful operation', content: { 'application/json': { schema: { $ref: '#/components/responses/SwaggerUrls', }, }, }, }, }, }, }, }, components: { responses: { SwaggerUrls: { type: 'array', items: { properties: { name: { type: 'string' }, url: { type: 'string' }, }, }, }, }, }, };

要点：

• info.title会显示在文档页面的标题位置，建议填写插件可读名称；
• paths中的 key 为接口路径，NocoBase 资源类接口路径通常形如/users:list、/swagger:get（资源名 +:+ action 名）；
• 响应结构可通过$ref引用components中定义的schemas/responses/parameters，跨文档引用时使用#/components/...相对引用；
• 若插件接口较多，可拆分为多个文件后自行合并导出，聚合层会对同路径内容做递归 merge。

3. 验证文档

• 重新构建并重启应用（开发模式下热重载后刷新即可）；
• 打开文档页面，在插件入口列表中找到对应插件名；
• 或直接请求/api/swagger:get?ns=plugins/{name}（{name}替换为插件名）查看该插件的 JSON 是否包含所写内容。

4. 编写规则参考

OpenAPI 规范（paths、tags、components、parameters、responses等字段的完整语法）请参考 Swagger 官方规范文档。本文档对象遵循 OpenAPI 3.x 结构，info、paths、components为最常用顶层字段。

访问控制与安全

• /api/swagger:get与/api/swagger:getUrls均要求登录用户（loggedIn）访问，未登录会返回 401；
• 管理员可在角色权限中配置pm.api-doc.documentation权限片段，控制哪些角色能访问 API 文档；
• 文档内容默认不包含敏感凭据，但 collections 文档会暴露业务表结构与字段定义，生产环境如需对特定角色隐藏，可通过权限设置限定访问范围。

小结

api-doc 插件让 NocoBase 的 HTTP API 文档做到了"零成本生成、随代码更新"：

• 内置插件，激活即用，管理后台与/api/swagger:get双通道输出；
• 六大文档入口覆盖总览、内核、插件、数据表四个维度，ns参数精确控制范围；
• 服务端通过 SwaggerManager 动态聚合静态文件与动态生成的 collections 文档，合并顺序与加载策略均有源码可查（server.ts、swagger/index.ts、loader.ts）；
• 插件开发者只需在src/swagger/index.ts写一个默认导出对象，即可让自己的插件接口出现在聚合文档中，适合作为团队内部接口规范落地的低成本方案。

【免费下载链接】nocobaseNocoBase is an open-source AI + no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase