Skip to content

接口文档 ​


版本说明 ​

  • = 1.2.0

背景说明 ​

springfox 与 knife4j 已停止维护,Bug 较多。
从 1.2.0 开始迁移到 springdoc,基于 javadoc 无注解生成 OpenAPI 结构。
框架移除内置 UI,推荐使用外置文档工具。

文档工具选择 ​

框架输出标准 OpenAPI,可选工具:

  • Apifox
  • Apipost
  • Postman
  • Torna
  • Knife4j

Swagger -> SpringDoc 映射 ​

注意:javadoc 只能替代基础功能,复杂场景仍需注解。

swaggerspringdocjavadoc
@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.apifox.cn/

视频教程: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 官方文档。

砚考 · 让每一次考试都经得起检验