目录

接口文档

项目使用 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) 文章。

每个服务都会启动 Swagger 的接口文档,方便开发者进行 API 调试。下述的内容,使用 system-server 系统服务举例子,它的端口是 48081。

注意!注意!注意!文章部分图中,看到的是 48080 端口,实际你都填写 48081。

# 1. Apifox 使用

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

# 1.1 下载工具

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

为什么要下载 Apifox 桌面版?

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

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

Apifox 下载

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

Apifox 界面

# 1.2 API 导入

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

Apifox 界面 —— 导入

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

Apifox 界面 —— Swagger

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

Apifox 界面 —— Swagger

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

Apifox 界面 —— 接口管理

# 1.3 API 调试

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

Apifox 界面 —— 管理环境

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

Apifox 界面 —— 认证

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

Apifox 界面 —— 认证

# 2. Knife4j 使用

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

Knife4j 界面

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

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

其中,header-id 为租户编号,Authorization"Bearer test" 后面为用户编号(模拟哪个用户操作)。

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

Knife4j 调试

如何使用 Gateway 网关,聚合各个服务的接口文档?

参见 《微服务手册 —— 服务网关》 文档

# 3. Swagger 技术组件

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

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

Swagger 关闭

上次更新: 2023/03/05, 12:34:30

本站由 钟意 使用 Stellar 1.28.1 主题创建。
又拍云 提供CDN加速/云存储服务
vercel 提供托管服务
湘ICP备2023019799号-1
总访问 次 | 本页访问