接口文档

## 1. Apifox 使用

本小节，我们来将项目中的 API 接口，一键导入到 Apifox 中，并使用它发起一次 API 的调用。
1.1 下载工具
点击 Apifox首页，下载对应的 Apifox 桌面版。如下图所示：
为什么要下载 Apifox 桌面版？

![](/media/202408/2024-08-23_175941_488053.png)

![](/media/202408/2024-08-23_175946_761341.png)
## 1.2 API 导入
① 先点击「示例项目」，再点击「+」按钮，选择「导入」选项。

![](/media/202408/2024-08-23_180003_197581.png)
② 先选择「URL 导入」按钮，填写 Swagger 数据 URL 为 http://127.0.0.1:48081/v3/api-docs 。如果失败，则可以尝试 http://127.0.0.1:48080/v3/api-docs/all 解决。

![](/media/202408/2024-08-23_180026_087991.png)
③ 先点击「提交」按钮，再点击「确认导入」按钮，完成 API 接口的导入。

![](/media/202408/2024-08-23_180043_455830.png)

④ 导入完成后，点击「接口管理」按钮，可以查看到 API 列表。

![](/media/202408/2024-08-23_180100_533398.png)

#### ## 1.3 API 调试
① 先点击右上角「请选择环境」，再点击「管理环境」选项，填写测试环境的地址为 http://127.0.0.1:48081，并进行保存。

![](/media/202408/2024-08-23_180119_624273.png)

② 点击「管理后台 —— 认证」的「使用账号密码登录」接口，查看该 API 接口的定义。

![](/media/202408/2024-08-23_180135_987369.png)

③ 点击「运行」按钮，填写 Headers 的 tenant-id 为 1，再点击 Body 的「自动生成」按钮，最后点击「发送」按钮。

![](/media/202408/2024-08-23_180236_278404.png)
#### 1.4 常见问题
问题 ①：分页 GET 请求时，如果有 createTime 这种时间类型的数组参数，会报错。如下图所示：

![](/media/202408/2024-08-23_180250_719228.png)

答：把 createTime 左右两边的 [] 去掉，即可解决。

## 2. Knife4j 使用
#### 2.1 如何使用？
浏览器访问 http://127.0.0.1:48081/doc.html 地址，使用 Knife4j 查看 API 接口文档。

![](/media/202408/2024-08-23_180410_088278.png)

① 点击任意一个接口，进行接口的调用测试。这里，使用「管理后台 - 用户个中心」的“获得登录用户信息”举例子。

② 点击左侧「调试」按钮，并将请求头部的 header-id 和 Authorization 勾选上。

其中，header-id 为租户编号，Authorization 的 "Bearer test" 后面为用户编号（模拟哪个用户操作）。

③ 点击「发送」按钮，即可发起一次 API 的调用。

![](/media/202408/2024-08-23_180430_041103.png)

#### 2.2 如何开启登录？
生产环境下，建议 Knife4j 接口界面开启“安全认证”的功能，避免出现安全事故。

只需要在 knife4j.basic 配置项中，额外添加 Basic Auth 认证即可，如下所示：
`knife4j:
 basic:
 enable: true
 username: admin # Basic 认证用户名
 password: admin # Basic 认证密码`
	
#### 3. Swagger 技术组件
① 在 dtpc-spring-boot-starter-web 技术组件的 swagger 包，实现了对 Swagger 的封装。

② 如果想要禁用 Swagger 功能，可通过 springdoc.api-docs.enable 配置项为 false。一般情况下，建议 prod 生产环境进行禁用，避免发生安全问题。
![](/media/202408/2024-08-23_181330_182807.png)