微服务项目基于springdoc快速接入swagger3

环境说明

SpringBoot：3.0.2
SpringCloud：2022.0.0
SpringCloudAlibaba：2022.0.0.0-RC2
jackson：2.15.2
springdoc：2.2.0

这里也放一张官方与SpringBoot的版本关系

本次是基于SpringBoot3搭建的微服务做演示，因为升级SpringBoot3后，重构升级了很多东西，所以重新把swagger的引入记录一下。不过好消息是接入与使用非常简单。

我这里简单说一下我的项目结构，基本上是和ruoyi一样的

主要是common，这里我们也只需要关注swagger模块即可。我在common下新建了一个模块，名为swagger。主要作用是把swagger相关的东西放在这，方便管理。之后其他业务模块只需要引入sora-common即可完成对swagger的引入。后面也会基于此环境进行搭建与演示。

依赖引入

在swagger模块内引入springdoc依赖（只需要引入此依赖即可）

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>2.2.0</version>
</dependency>

继续引入jackson的依赖（序列化的时候需要用到，不引入会导致swagger页面500的错误，并且三个必须都要引入！！！）

<dependency>
  <groupId>com.fasterxml.jackson.core</groupId>
  <artifactId>jackson-databind</artifactId>
  <version>2.15.2</version>
</dependency>
<dependency>
  <groupId>com.fasterxml.jackson.core</groupId>
  <artifactId>jackson-core</artifactId>
	<version>2.15.2</version>
</dependency>
<dependency>
	<groupId>com.fasterxml.jackson.core</groupId>
	<artifactId>jackson-annotations</artifactId>
	<version>2.15.2</version>
</dependency>

配置文件写入

配置文件主要就是文档内的介绍，不引入也可以，在这里对页面进行自定义展示

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI springOpenAPI() {
        return new OpenAPI().info(new Info()
                .title("sora后端文档")
                .description("展示所有后端接口文档与说明～")
                .version("1.0.0"));
    }

}

下面是配置文件的内容，前者是文档的自定义路径，后者则是路径自定义，路径自定义可以更迅速的转到后端文档地址

springdoc:
  api-docs:
    # 文档自定义路径
    path: /sora/doc
  swagger-ui:
    # html网页自定义路径
    path: /sora-doc.html

文档自定义：

路径自定义：

基本注解说明与页面展示

这里没有找到官方对各注解的说明，这里我就手动写了，如何有错欢迎留言🙏

作用在类上，对各方法进行分组
@Tag(name = “AuthController”, description = “鉴权控制器”)

例如下图，分别在两个类上标注对应的name与desc，页面按照tag进行分组展示

作用在方法上，对方法进行命名与描述补充
@Operation(summary = “登陆”, description = “通过用户名与密码登陆”)

作用在参数上，对参数进行描述
@Parameter(description = “用户名”)

最后是对实体类的描述，使用@Schema注解描述对象和字段释义

@Data
@AllArgsConstructor
@NoArgsConstructor
@Schema(description = "用户对象")
@TableName("sora_user")
public class User {
    /**
     * 主键
     */
    private String id;
    /**
     * 用户名
     */
    @Schema(description = "用户名")
    @Excel(name = "用户名")
    private String name;
    /**
     * 性别
     */
    @Schema(description = "性别")
    @Excel(name = "性别", replace = {"男_1","女_0"})
    private String sex;
    /**
     * 出生日期
     */
    @Schema(description = "出生日期")
    @Excel(name = "出生日期")
    private Date birthday;
    /**
     * 密码
     */
    @Schema(description = "密码")
    private String password;
    /**
     * 手机号
     */
    @Schema(description = "手机号")
    @Excel(name = "手机号")
    private String phone;
    /**
     * 邮箱
     */
    @Schema(description = "邮箱")
    @Excel(name = "邮箱")
    private String email;
    /**
     * 权限id
     */
    @Schema(description = "权限id")
    private Integer roleLevel;
    /**
     * 创建时间
     */
    @Schema(description = "创建时间")
    @Excel(name = "创建时间")
    private Date createTime;
    /**
     * 是否被封禁
     */
    @Schema(description = "是否被封禁")
    @Excel(name = "是否被封禁", replace = {"是_1","否_0"})
    private String banned;
    /**
     * 是否被禁用
     */
    @Schema(description = "是否被禁用")
    @Excel(name = "是否被禁用", replace = {"是_1","否_0"})
    private String disabled;
}