项目使用 Swagger 实现 RESTful API 的接口文档，提供两种解决方案：

*【推荐】 Apifox (opens new window)：强大的 API 工具，支持 API 文档、API 调试、API Mock、API 自动化测试

• Knife4j：简易的 API 工具，仅支持 API 文档、API 调试

为什么选择 Swagger 呢？

Swagger 通过 Java 注解实现 API 接口文档的编写。相比使用 Java 注释的方式，注解提供更加规范的接口定义方式，开发体验更好。

如果你没有学习 Swagger，可以阅读 《芋道 Spring Boot API 接口文档 Swagger 入门 》 (opens new window) 文章。

1. Apifox 使用

本小节，我们来将项目中的 API 接口，一键导入到 Apifox 中，并使用它发起一次 API 的调用。

1.1 下载工具

点击 Apifox (opens new window) 首页，下载对应的 Apifox 桌面版。如下图所示：

为什么要下载 Apifox 桌面版？

艿艿已经卸载 Postman，使用 Apifox 进行替代。国产软件，yyds 永远滴神！

国内很多互联网公司，包括百度、阿里、腾讯、字节跳动等等在内，都在使用 Apifox 作为 API 工具。

解压后，双击进行安装即可。黑色界面，非常酷炫。

1.2 API 导入

① 先点击「示例项目」，再点击「+」按钮，选择「导入」选项。

② 先选择「URL 导入」按钮，填写 Swagger 数据 URL 为 http://127.0.0.1:48080/v3/api-docs。

③ 先点击「提交」按钮，再点击「确认导入」按钮，完成 API 接口的导入。

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

1.3 API 调试

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

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

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

注意，登录接口不要填写 socialType、socialCode、socialState 这三个参数，它们是三方登录的参数。一定要去掉，不然会报错噢！

1.4 常见问题

问题 ①：分页 GET 请求时，如果有 createTime 这种时间类型的数组参数，会报错。如下图所示：

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

2. Knife4j 使用

浏览器访问 http://127.0.0.1:48080/doc.html (opens new window) 地址，使用 Knife4j 查看 API 接口文档。

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

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

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

如果不勾选，会出现 "请求的租户标识未传递，请进行排查" 或 "账号未登录" 错误。

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

3. Swagger 技术组件

① 在 yudao-spring-boot-starter-web (opens new window) 技术组件的 swagger (opens new window) 包，实现了对 Swagger 的封装。

② 如果想要禁用 Swagger 功能，可通过 springdoc.api-docs.enable 配置项为 false。一般情况下，建议 prod 生产环境进行禁用，避免发生安全问题。