SpringDoc API文档工具集成SpringBoot - Swagger3

1、引言

之前在Spring Boot项目中一直使用的是SpringFox提供的Swagger库,发现已经超过3年没出新版本了!SpringDoc是一款可以结合Spring Boot使用的API文档生成工具,基于OpenAPI 3,是一款更好用的Swagger库!值得一提的是SpringDoc不仅支持Spring WebMvc项目,还可以支持Spring WebFlux项目,甚至Spring Rest和Spring Native项目。
Swagger规范已经重命名为OpenAPI规范。Swagger2指的是2017年停止更新的io.swagger包,而Swagger3指的是2017年将Swagger2重新命名为io.swagger.core.v3包。

  1. Swagger规范已经重命名为OpenAPI规范。Swagger2指的是2017年停止更新的io.swagger包,而Swagger3指的是2017年将Swagger2重新命名为io.swagger.core.v3包。
  2. Springfox是Spring的一种OpenAPI实现。其中,Springfox-Swagger2通常被大多数国内所指的Swagger2,但与上述的Swagger2不是同一个意思。它使用的依赖就是上述提到的Swagger2,并且和Swagger2一样,很久没有更新了。
  3. Springdoc是Spring的另一种OpenAPI实现,它依赖于上述的Swagger3。目前,Springdoc相对较活跃,因此Swagger的升级方向是Springdoc。

Swagger2 已经停止维护了,取而代之的是 Swagger3。

2、使用步骤

2.1导入依赖

xml 复制代码
<!-- https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-ui -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.7.0</version>
</dependency>

2.2 删除Swagger2的依赖和配置

推荐使用Maven helper插件
搜索springfox,找到依赖并排除。
刷新依赖,删除与Swagger2相关配置,重启应用。

现在可以看到已经成功进入了。

2.3 配置(可以不用)

如果需要写配置的话,配置类和配置文件都需要写。

配置类如下:

java 复制代码
@Configuration
@OpenAPIDefinition(info =
@Info(title = "用户模块API文档", version = "1.0", description = "用户模块API文档 v1.0")
)
public class Swagger3Configuration {

    @Bean
    public GroupedOpenApi restApi() {
        return GroupedOpenApi.builder()
                .group("user-service")
                .pathsToMatch("/user-service/**")
                .build();
    }

}

配置文件如下

yaml 复制代码
springdoc:
  swagger-ui:
    # 修改Swagger UI路径
    path: /swagger-ui.html
    # 开启Swagger UI界面
    enabled: true
  api-docs:
    # 修改api-docs路径
    path: /v3/api-docs
    # 开启api-docs
    enabled: true
  # 配置需要生成接口文档的扫描包
  packages-to-scan: com.sifan.user.controller
  # 配置需要生成接口文档的接口路径, /** 表示匹配所有
  paths-to-match: /**

3、Swagger 注解 与 SpringDoc 对应注解的对应关系

Swagger 注解 Springdoc 对应注解 注解作用 示例
@Api @Tag 用于定义 API 全局信息 @Tag(name = "User Management")
@ApiOperation @Operation 用于定义单个 API 操作的信息 @Operation(summary = "Get User by ID")
@ApiParam @Parameter 用于定义操作参数的信息 @Parameter(name = "userId", description = "User ID")
@ApiResponse @APIResponse 用于定义操作的响应信息 @APIResponse(responseCode = "200", description = "Successful")
@ApiResponses @APIResponses 用于定义多个操作响应信息 @APIResponses(value = { @APIResponse(responseCode = "200", description = "Successful"), @APIResponse(responseCode = "404", description = "Not Found") })
@ApiModel @Schema 用于定义模型对象的信息 @Schema(name = "User", description = "User information")
@ApiModelProperty @Schema 用于定义模型属性的信息 @Schema(description = "User's name")
@ApiIgnore @Hidden 用于指示忽略特定的 API 元素 @Hidden
@ApiImplicitParam @ParameterObject 用于定义隐式的操作参数信息 @ParameterObject
@ApiImplicitParams @Parameters 用于定义多个隐式操作参数信息 @Parameters({ @ParameterObject, @ParameterObject })

4、 可能会出现的问题

出现下面的问题表示Swagger2的依赖没有删除干净
出现下面:No operations defined in spec!可能是只写了配置类,忘记写配置文件了,或者配置文件没写全没写对。

添加依赖后重启应用,访问:http://127.0.0.1:9091/swagger-ui/index.html因为以前使用的shiSwagger2所以会出现下面的情况。

相关推荐
亦枫Leonlew1 小时前
微积分复习笔记 Calculus Volume 1 - 4.7 Applied Optimization Problems
笔记·数学·微积分·1024程序员节
小肥象不是小飞象1 小时前
(六千字心得笔记)零基础C语言入门第八课——函数(上)
c语言·开发语言·笔记·1024程序员节
一个通信老学姐10 小时前
专业130+总400+武汉理工大学855信号与系统考研经验电子信息与通信工程,真题,大纲,参考书。
考研·信息与通信·信号处理·1024程序员节
力姆泰克11 小时前
看电动缸是如何提高农机的自动化水平
大数据·运维·服务器·数据库·人工智能·自动化·1024程序员节
力姆泰克11 小时前
力姆泰克电动缸助力农业机械装备,提高农机的自动化水平
大数据·服务器·数据库·人工智能·1024程序员节
程思扬11 小时前
为什么Uptime+Kuma本地部署与远程使用是网站监控新选择?
linux·服务器·网络·经验分享·后端·网络协议·1024程序员节
转世成为计算机大神11 小时前
网关 Spring Cloud Gateway
java·网络·spring boot·1024程序员节
paopaokaka_luck11 小时前
基于Spring Boot+Vue的助农销售平台(协同过滤算法、限流算法、支付宝沙盒支付、实时聊天、图形化分析)
java·spring boot·小程序·毕业设计·mybatis·1024程序员节
幼儿园园霸柒柒12 小时前
第七章: 7.3求一个3*3的整型矩阵对角线元素之和
c语言·c++·算法·矩阵·c#·1024程序员节
好想有猫猫12 小时前
【51单片机】串口通信原理 + 使用
c语言·单片机·嵌入式硬件·51单片机·1024程序员节