后端框架 · RuoYi-Vue-Plus框架功能框架相关
接口文档
版本说明
-
= 4.3.0
背景说明
springfox 与 knife4j 已停止维护，Bug 较多。
从 4.3.0 开始迁移到 springdoc，基于 javadoc 无注解生成 OpenAPI 结构。
框架移除内置 UI，推荐使用外置文档工具。
文档工具选择
框架输出标准 OpenAPI，可选工具：
ApifoxApipostPostmanTornaKnife4j
Swagger -> SpringDoc 映射
注意：javadoc 只能替代基础功能，复杂场景仍需注解。
| swagger | springdoc | javadoc |
|---|---|---|
| @Api(name = "xxx") | @Tag(name = "xxx") | 类注释第一行 |
| @Api(description= "xxx") | @Tag(description= "xxx") | 类注释 |
| @ApiOperation | @Operation | 方法注释 |
| @ApiIgnore | @Hidden | 无 |
| @ApiParam | @Parameter | 方法 @param 注释 |
| @ApiImplicitParam | @Parameter | 方法 @param 注释 |
| @ApiImplicitParams | @Parameters | 多个 @param 注释 |
| @ApiModel | @Schema | 实体类注释 |
| @ApiModelProperty | @Schema | 字段注释 |
| @ApiModelProperty(hidden = true) | @Schema(accessMode = READ_ONLY) | 无 |
| @ApiResponse | @ApiResponse | 方法 @return 注释 |
推荐 Apifox
视频教程：https://www.bilibili.com/video/BV1mr4y1j75M?p=8
支持文档编写、接口调试、Mock、压测与自动化测试。
使用 OpenAPI 接入（Apifox）
1. 创建项目
下载客户端或使用 Web 版创建项目。
2. 开启自动同步
进入项目设置，找到自动同步。
3. 创建数据源
根据项目文档分组创建数据源（拉取 /v3/api-docs）。
数据源URL格式 http://后端ip:端口/v3/api-docs/组名
示例：
http://localhost:8080/v3/api-docs/1.演示模块http://localhost:8080/v3/api-docs/2.通用模块http://localhost:8080/v3/api-docs/3.系统模块http://localhost:8080/v3/api-docs/4.代码生成模块
也可不分组统一导入：
http://localhost:8080/v3/api-docs
4. 导入接口
在“接口管理 -> 项目概览”点击“立即导入”。
后续可按策略自动同步，也可手动导入。
5. 鉴权设置（注意版本）
>= 5.X
4.X
默认 key 为 Authorization：
使用 Apifox-Helper
官方文档：https://docs.apifox.com/doc-5743620
1. 创建 ApiKey
2. 插件安装
3. 插件界面
打开项目时显示：
可以手动点击刷新：
如果觉得地方不够可以使用悬浮窗：
悬浮窗，拉到合适大小：
可以切换分屏位置：
4. 上传 Apidoc
通过插件上传时，建议将各模块单独创建为模块。
上传流程：
查看控制台输出与文档：
5. 插件配置
更多使用方法请参考 Apifox 官方文档。