RuoYi-Vue-Plus 接口文档（313）

版本 >= 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/

支持文档编写接口调试 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

application.yml 文件

# api地址(数据源URL)：http://localhost:8080/v3/api-docs/1.演示模块
springdoc:
  api-docs:
    # 是否开启接口文档
    enabled: true
  #这里定义了两个分组，可定义多个，也可以不定义
  group-configs:
    - group: 1.演示模块
      packages-to-scan: org.dromara.demo
    - group: 2.通用模块
      packages-to-scan: org.dromara.web
    - group: 3.系统模块
      packages-to-scan: org.dromara.system
    - group: 4.代码生成模块
      packages-to-scan: org.dromara.generator

4. 自动导入

选择 接口管理 项目概览 点击立即导入 并等待导入完成

后续会根据策略每3个小时自动导入一次
每次重新进入apifox也会自动同步一次
后端有改动也可以手动点击导入

5.设置鉴权（注意版本号）

选择接口管理 项目概览 全局参数找到Auth 按照如下配置

key对应项目配置默认为 Authorization

# Sa-Token配置
sa-token:
  multiple:
    login:
      # token名称 (同时也是cookie名称)
      token-name: Authorization
# api地址(数据源URL)：http://localhost:8080/v3/api-docs/1.演示模块
springdoc:
  components:
    # 鉴权方式配置
    security-schemes:
      apiKey:
        type: APIKEY
        in: HEADER
        name: ${sa-token.token-name}

开发喵星球