cool-admin(midway版)后端API文档：生成与配置终极指南

cool-admin(midway版)后端API文档生成与配置终极指南【免费下载链接】cool-admin-midway cool-admin(midway版)一个很酷的后台权限管理框架模块化、插件化、CRUD极速开发永久开源免费基于midway.js 3.x、typescript、typeorm、mysql、jwt、vue3、vite、element-ui等构建项目地址: https://gitcode.com/gh_mirrors/co/cool-admin-midway想要快速生成和管理你的 cool-admin(midway版) 后端 API 文档吗 本文将为你详细介绍如何配置和生成专业的 Swagger API 文档让你的后端接口一目了然什么是 cool-admin(midway版) 的自动API文档生成cool-admin(midway版) 是一个基于 Midway.js 3.x、TypeScript 和 TypeORM 构建的现代化后台权限管理框架。它内置了强大的API 文档自动生成功能通过简单的配置即可为你的所有接口生成标准的 Swagger 文档。这个功能基于项目的 EPSEntity, Path, Service系统能够自动扫描所有控制器和实体生成完整的 API 文档无需手动编写每个接口的描述。开启API文档生成功能 第一步启用EPS配置要使用 cool-admin(midway版) 的 API 文档功能首先需要在配置文件中启用 EPS 系统。打开配置文件src/config/config.local.ts找到cool配置部分确保eps设置为truecool: { // 实体与路径跟生成代码、前端请求、swagger文档相关 eps: true, // 是否自动导入模块数据库 initDB: true, // 判断是否初始化的方式 initJudge: db, // 是否自动导入模块菜单 initMenu: true, }第二步Swagger模块配置cool-admin(midway版) 内置了完整的 Swagger 模块位于src/modules/swagger/这个模块会自动处理所有 API 文档的生成和展示。模块的主要文件包括config.ts- Swagger 基本配置builder.ts- 文档构建器controller/index.ts- 文档访问控制器event/app.ts- 应用事件处理第三步访问API文档启动项目后访问以下地址即可查看自动生成的 API 文档http://localhost:8001/swagger如果你需要获取原始的 Swagger JSON 数据可以访问http://localhost:8001/swagger/json配置Swagger文档信息 ✨自定义文档基本信息在src/modules/swagger/config.ts中你可以自定义 Swagger 文档的基本信息base: { openapi: 3.1.0, info: { title: Cool Admin 在线API文档, version: 8.x, description: 本文档是由Cool Admin内部自动构建完成, contact: { name: 开发文档, url: https://cool-js.com, }, }, servers: [ { url: http://127.0.0.1:${app?.getConfig(koa.port) || 8001}, description: 本地后台地址, }, ], }配置服务器地址Swagger 支持配置多个服务器地址方便在不同环境间切换servers: [ { url: http://localhost:8001, description: 本地开发环境, }, { url: https://api.example.com, description: 生产环境, }, ]如何让控制器自动生成API文档 使用CoolController装饰器cool-admin(midway版) 使用CoolController装饰器来自动识别和生成 API 文档。例如查看用户管理模块的控制器src/modules/base/controller/admin/sys/user.tsCoolController({ api: [add, delete, update, info, list, page], entity: BaseSysUserEntity, service: BaseSysUserService, }) export class BaseSysUserController extends BaseController { // 自定义接口也会自动生成文档 Post(/move, { summary: 移动部门 }) async move( Body(departmentId) departmentId: number, Body(userIds) userIds: [] ) { // 业务逻辑 } }支持的API操作类型CoolController装饰器的api参数支持以下操作类型add- 新增数据delete- 删除数据update- 更新数据info- 获取单条数据list- 获取列表数据page- 分页查询数据实体与API文档的映射关系 自动生成Schema定义cool-admin(midway版) 会自动将 TypeORM 实体转换为 Swagger Schema。例如查看商品实体src/modules/demo/entity/goods.tsEntity(demo_app_goods) export class DemoAppGoodsEntity extends BaseEntity { Column({ comment: 标题 }) title: string; Column({ comment: 图片 }) pic: string; Column({ comment: 价格, type: decimal, precision: 5, scale: 2 }) price: number; }这个实体会自动生成对应的 Swagger Schema包含字段类型、描述等信息。数据类型映射系统会自动将 TypeScript/TypeORM 类型映射为 Swagger 类型string→stringnumber→numberbigint→integerdatetime→string(ISO8601格式)高级配置技巧 自定义接口文档除了自动生成的 CRUD 接口你也可以为自定义接口添加文档Post(/custom, { summary: 自定义接口, description: 这是一个自定义的业务接口 }) async customMethod( Body(param1) param1: string, Body(param2) param2: number ) { return this.ok(自定义响应); }配置安全认证Swagger 文档支持配置 API 密钥认证在src/modules/swagger/config.ts中components: { securitySchemes: { ApiKeyAuth: { type: apiKey, name: Authorization, in: header, }, }, }分组显示API系统会自动按模块对 API 进行分组每个模块会显示为一个独立的标签页。分组信息来自模块的配置文件如src/modules/base/config.tsexport default { name: 基础模块, description: 系统基础功能模块, }常见问题与解决方案 问题1访问/swagger显示Eps未开启解决方案检查src/config/config.local.ts中的eps配置是否设置为true。问题2API文档中没有显示某些接口解决方案确保控制器使用了CoolController装饰器检查控制器是否在模块中正确注册确认实体类正确定义了字段和注释问题3Swagger文档加载缓慢解决方案在生产环境中可以考虑缓存生成的 Swagger JSON 数据避免每次请求都重新生成。问题4自定义接口没有文档解决方案为自定义接口方法添加Post、Get等装饰器并提供summary参数。最佳实践建议 1. 保持实体注释清晰为实体字段添加详细的注释这些注释会自动显示在 API 文档中Column({ comment: 用户姓名最长50个字符 }) name: string; Column({ comment: 用户邮箱用于登录和找回密码 }) email: string;2. 合理使用模块化将相关功能放在同一个模块中这样在 Swagger 文档中会自动分组显示便于管理和查看。3. 定期更新文档每次添加新的接口或修改现有接口后重启服务即可自动更新 API 文档。4. 利用文档进行测试Swagger UI 不仅提供文档查看功能还支持直接在界面上测试 API 接口这对于开发和调试非常有帮助。总结 cool-admin(midway版) 的 API 文档生成功能极大地简化了后端开发者的文档维护工作。通过简单的配置和约定就能自动生成专业、完整的 API 文档。核心优势✅ 零配置自动生成✅ 基于实体自动生成Schema✅ 支持自定义接口文档✅ 按模块分组显示✅ 支持在线测试现在你已经掌握了 cool-admin(midway版) API 文档的完整配置和使用方法。立即开始使用这个强大的功能让你的后端开发更加高效和专业吧记住好的 API 文档不仅是给前端开发者的礼物也是给自己未来的礼物。清晰的文档能大大减少沟通成本提高团队协作效率。【免费下载链接】cool-admin-midway cool-admin(midway版)一个很酷的后台权限管理框架模块化、插件化、CRUD极速开发永久开源免费基于midway.js 3.x、typescript、typeorm、mysql、jwt、vue3、vite、element-ui等构建项目地址: https://gitcode.com/gh_mirrors/co/cool-admin-midway创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考