# 接口文档
- - -
## 版本 >= `4.3.0`
## 说明
由于 `springfox` 与 `knife4j` 均停止维护 bug众多
故从 `4.3.0` 开始 迁移到 `springdoc` 框架
基于 `javadoc` 无注解零入侵生成规范的 `openapi` 结构体
由于框架自带文档UI功能单一扩展性差 故移除自带UI 建议使用外置文档工具
## 文档工具使用
由于框架采用 `openapi` 行业规范 故市面上大部分的框架均支持 可自行选择
例如: `apifox` `apipost` `postman` `torna` `knife4j` 等 根据对应工具的文档接入即可
## Swagger升级SpringDoc指南
常见功能如下 其他功能自行挖掘
**注意: `javadoc` 只能替换基础功能 特殊功能还需要使用注解实现**
| swagger | springdoc | javadoc |
|----------------------------------|---------------------------------|--------------------|
| @Api(name = "xxx") | @Tag(name = "xxx") | java类注释第一行 |
| @Api(description= "xxx") | @Tag(description= "xxx") | java类注释 |
| @ApiOperation | @Operation | java方法注释 |
| @ApiIgnore | @Hidden | 无 |
| @ApiParam | @Parameter | java方法@param参数注释 |
| @ApiImplicitParam | @Parameter | java方法@param参数注释 |
| @ApiImplicitParams | @Parameters | 多个@param参数注释 |
| @ApiModel | @Schema | java实体类注释 |
| @ApiModelProperty | @Schema | java属性注释 |
| @ApiModelProperty(hidden = true) | @Schema(accessMode = READ_ONLY) | 无 |
| @ApiResponse | @ApiResponse | java方法@return返回值注释 |
# 建议使用 `Apifox`(常见问题有其他对接方式)
官网连接: [https://www.apifox.cn/](https://www.apifox.cn/)
视频教程: [springdoc与apifox配合使用](https://www.bilibili.com/video/BV1mr4y1j75M?p=8&vd_source=8f52c77be3233dbdd1c5e332d4d45bfb)
支持 文档编写 接口调试 Mock 接口压测 自动化测试 等一系列功能
### 接入框架
> 1.下载或使用web在线版 创建一个自己的项目
> 2.进入项目 选择项目设置 找到自动同步
> 3.根据项目内所有文档组完成所有数据源创建(拉取后端`openapi`结构体)
数据源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.选择 接口管理 项目概览 点击立即导入 并等待导入完成
后续会根据策略每3个小时自动导入一次
每次重新进入apifox也会自动同步一次
后端有改动也可以手动点击导入
> 5.(注意版本号)设置鉴权 选择接口管理 项目概览 找到Auth 按照如下配置
**版本号: >= 5.X**
**版本号: 4.X**
> key对应项目配置 默认为 `Authorization`
