中国 帮助

接口文档

版本说明 = 4.3.0 背景说明 springfox 与 knife4j 已停止维护,Bug 较多。 从 4.3.0 开始迁移到 springdoc,基于 javadoc 无注解生成 OpenAPI 结构。 框

接口文档
封面

> 本文整理自平台文档 docs/wujies/5.x/ruoyi-vue-plus/framework/association/doc.mdx,用于站点内容演示。

(https://console.wujies.cn/remote-apps/cms-assets/doc-afe088d69e92-cover.svg)

  • - -

版本说明

  • >= 4.3.0

背景说明

springfox 与 knife4j 已停止维护,Bug 较多。 从 4.3.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

![输入图片说明](https://foruda.gitee.com/images/1678976476639902970/f1617b40_1766278.png "屏幕截图")

支持文档编写、接口调试、Mock、压测与自动化测试。

使用 OpenAPI 接入(Apifox)

### 1. 创建项目

下载客户端或使用 Web 版创建项目。

![输入图片说明](https://foruda.gitee.com/images/1678976502850663851/7bbd8728_1766278.png "屏幕截图")

### 2. 开启自动同步

进入项目设置,找到自动同步。

![输入图片说明](https://foruda.gitee.com/images/1678976508918240326/6a4a61a8_1766278.png "屏幕截图")

### 3. 创建数据源

根据项目文档分组创建数据源(拉取 /v3/api-docs)。<br /> 数据源URL格式 http://后端ip:端口/v3/api-docs/组名<br />

示例:

  • http://localhost:8080/v3/api-docs/1.演示模块 <br />
  • http://localhost:8080/v3/api-docs/2.通用模块 <br />
  • http://localhost:8080/v3/api-docs/3.系统模块 <br />
  • http://localhost:8080/v3/api-docs/4.代码生成模块 <br />

也可不分组统一导入:

  • http://localhost:8080/v3/api-docs

![输入图片说明](https://foruda.gitee.com/images/1678976514385097727/05c7e0a6_1766278.png "屏幕截图") ![输入图片说明](https://foruda.gitee.com/images/1686626073422245046/df4b6a54_1766278.png "屏幕截图") ![输入图片说明](https://foruda.gitee.com/images/1678976527495742967/79836e7f_1766278.png "屏幕截图")

### 4. 导入接口

在“接口管理 -> 项目概览”点击“立即导入”。 后续可按策略自动同步,也可手动导入。

![输入图片说明](https://foruda.gitee.com/images/1678976534677430926/f32c64c5_1766278.png "屏幕截图")

### 5. 鉴权设置(注意版本)

>= 5.X

![输入图片说明](https://foruda.gitee.com/images/1690966897370710566/6a688aea_1766278.png "屏幕截图")

4.X

![输入图片说明](https://foruda.gitee.com/images/1678976539608390075/77246461_1766278.png "屏幕截图")

默认 key 为 Authorization:

![输入图片说明](https://foruda.gitee.com/images/1678976544342001474/c2ff85d3_1766278.png "屏幕截图") ![输入图片说明](https://foruda.gitee.com/images/1678976549237304743/bcdfadda_1766278.png "屏幕截图")

使用 Apifox-Helper

官方文档:https://docs.apifox.com/doc-5743620

### 1. 创建 ApiKey

![输入图片说明](https://foruda.gitee.com/images/1753102590437056663/6a9604f0_4959041.png "屏幕截图")

![输入图片说明](https://foruda.gitee.com/images/1753102633891623034/69428c34_4959041.png "屏幕截图")

![输入图片说明](https://foruda.gitee.com/images/1753102720063363982/16c95783_4959041.png "屏幕截图")

### 2. 插件安装

![输入图片说明](https://foruda.gitee.com/images/1753100791977471774/ac854016_4959041.png "屏幕截图")

### 3. 插件界面

打开项目时显示:

![输入图片说明](https://foruda.gitee.com/images/1753100862453931298/0d887f2a_4959041.png "屏幕截图")

可以手动点击刷新:

![输入图片说明](https://foruda.gitee.com/images/1753100872505206360/109c6242_4959041.png "屏幕截图")

如果觉得地方不够可以使用悬浮窗:

![输入图片说明](https://foruda.gitee.com/images/1753100989040629656/37f2a84c_4959041.png "屏幕截图")

悬浮窗,拉到合适大小:

![输入图片说明](https://foruda.gitee.com/images/1753100996801877387/7e77e3b9_4959041.png "屏幕截图")

可以切换分屏位置:

![输入图片说明](https://foruda.gitee.com/images/1753101038593037694/5a25975e_4959041.png "屏幕截图")

![输入图片说明](https://foruda.gitee.com

本文导览

(https://console.wujies.cn/remote-apps/cms-assets/doc-afe088d69e92-guide.svg)

章节导览
THE END

喜欢就支持以下吧

评论区需要浏览器启用 JavaScript 才能加载。

回到内容