接口文档
版本说明
= 1.2.0
背景说明
springfox 与 knife4j 已停止维护,Bug 较多。
从 1.2.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/demo/v3/api-docs演示服务http://localhost:8080/auth/v3/api-docs认证服务http://localhost:8080/resource/v3/api-docs资源服务http://localhost:8080/system/v3/api-docs系统服务http://localhost:8080/code/v3/api-docs代码生成服务


4. 导入接口
在“接口管理 -> 项目概览”点击“立即导入”。
后续可按策略自动同步,也可手动导入。

5. 鉴权设置(注意版本)
>= 2.X

1.X

默认 key 为 Authorization:


使用 Apifox-Helper
官方文档:https://docs.apifox.com/doc-5743620
1. 创建 ApiKey



2. 插件安装

3. 插件界面
打开项目时显示:

可以手动点击刷新:

如果觉得地方不够可以使用悬浮窗:

悬浮窗,拉到合适大小:

可以切换分屏位置:


在插件中使用方式与web版本、客户端版本基本一致,如果只是简单进行测试可以直接使用,在此不再赘述。
下面重点说明使用插件进行 Apidoc 上传。
4. 上传 Apidoc
之前的用法是把所有的接口导入到默认模块中,按照文件夹来进行区分。
插件上传的时候需要选择模块,如果不单独设置,不会像原有那样可以选择文件夹。
因此这里将各模块单独独立出来,效果如下:

新建模块:


上传流程:



查看控制台输出与文档:


5. 插件配置

更多使用方法请参考 Apifox 官方文档。