本文最后更新于 1681 天前，其中的信息可能已经有所发展或是发生改变。

SpringBoot 整合Swagger3 生成 API 接口文档

相比于之前的 Swagger2，Swagger3 无疑新添了更多的特点，而相对集中地，主要集中在如下几点。

支持 OpenApi 3.0.3
兼容 Swagger2 的注释，而且进一步丰富了 open API 3.0 的规范
支持 Webflux

既然 Swagger3 有了这么多的改变，那用法是不是还和 Swagger2 一样呢？答案是：不一样。

不过虽然两者的使用方式不一样，但是总体流程还是差不多了，只不过有些步骤有所小变动而已，只要你掌握了 Swagger2 的使用方法，那使用 Swagger3 起来就是需要注意小改动就行了。那接下来，我们就来看看，如何利用 Spring Boot 来集成 Swagger3，对我们的 Swagger2 进行一次升级！

引入依赖

创建项目后，在 pom.xml 文件中引入 Swagger3 的相关依赖。回忆一下，我们集成 Swagger2 时，引入的依赖如下：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

而在 Swagger3 中，我们不需要再引入两个不同的依赖了，我们只需要引入一个依赖就足够，具体引入的依赖如下：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

而这部分，Swagger2 和 Swagger3 就有所不同了，Swagger2 需要添加两项不同依赖，而 Swagger3 只用添加一项依赖就可以了。

构建 Swagger 配置类

为了统一管理 Swagger，这里还是推荐给 Swagger3 添加一个配置类。当然这里也可以根据自己的需求，可要可不要，但总体来说还是建议配置。

平常在工作中，Swagger 的使用仅限于在开发环境，而在生产环境中，我们是要将其移除的。这里为了灵活管理，推荐大家在项目配置文件 application.yml 中添加关于 Swagger 开关的配置，比如这里我添加的配置如下，true 则代表开启 Swagger，false 则表示关闭 Swagger。

swagger:
  enabled: true

配置完成之后，我们就需要在 Swagger 配置类中获取 Swagger 开关的值了，关于具体用法就可以看下边配置代码。

package com.hcxt.sms.config;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * @author: GuoLiangJun
 * @date: Created in 2021/12/13 21:59
 * Description: swagger 配置类
 * Created with IntelliJ IDEA.
 */
@Configuration
@EnableOpenApi
public class SwaggerConfig {

    @Value("${swagger.enabled}")
    Boolean swaggerEnabled;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo()).enable(swaggerEnabled)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.hcxt.sms.controller"))
                // 指定路径处理，PathSelectors.any()代表不过滤任何路径
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        // 作者信息
        Contact contact = new Contact("chinamobile", "https://chinamobile.com","service@chinamobile.com");
        return new ApiInfoBuilder()
                .title("短信发送API文档接口")
                .description("api接口文档")
                .version("1.0")
                .contact(contact)
                .license("Apache 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
                .build();
    }
}

这里的配置和 Swagger2 大同小异，这里最大的区别在于加入了从配置文件中获取 Swagger 开关的属性。这里也可以选择添加到 Swagger2 的配置类中，同样通过配置文件来控制是否开启 Swagger2。此外，还有就是 DocumentationType 属性的不同了，Swagger2 中我们使用的是 SWAGGER_2，而在 Swagger3 中，我们使用的则是 OAS_30。其实点进去 DocumentationType 的源码我们就可以发现，Swagger 已经是给我们定义好的，你用的是哪一个版本的 Swagger，那我们使用的属性值应该选择对应版本。三个版本的属性值对应如下：

编写实体类

完成上面的步骤之后，我们的 Swagger 就配置好了，接下来我们就添加一个接口来看看 Swagger3 和 Swagger2 的不同。

1.新建实体类

package com.hcxt.sms.domain.vo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import javax.validation.constraints.Size;
import javax.validation.constraints.NotBlank;

/**
 * @author: GuoLiangJun
 * @date: Created in 2021/12/10 20:42
 * Description:
 * Created with IntelliJ IDEA.
 */

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(description = "发送信息参数类")
public class SendMessageInfo {

    @NotBlank(message = "手机号码不能为空!")
    @Size(min = 11,max = 11, message = "手机号码长度不正确")
    @ApiModelProperty(value = "手机号码")
    private String phoneNumber;

    @NotBlank(message = "ip地址不能为空!")
    @ApiModelProperty(value = "ipv4")
    private String ipv4Address;

}

2.新建接口

@RestController
@RequestMapping("/api")
@Slf4j
@Api(tags = "短信api")
public class SmsController {

    @Autowired
    SmsService smsService;

    @PostMapping("/sendLoginMessage")
    @ApiOperation(value = "发送登录验证码功能")
    @ApiResponses({
            @ApiResponse(code = 0,message = "请求成功",response=ResMsg.class),
            @ApiResponse(code = 1,message = "请求失败",response=ResMsg.class)
    })
    public ResMsg sendLoginMessage(@RequestBody @Valid SendMessageInfo sendMessageInfo){
        log.info(sendMessageInfo.toString());
        return smsService.sendLoginMessage(sendMessageInfo);
    }
}

查看并测试接口

启动我们的项目，然后在浏览器中访问如下地址，就可以访问项目的接口文档了。

http://localhost:28080/sms/swagger-ui/index.html

访问上面的地址后，如果出现下面的界面，则说明集成 Swagger3 就成功了。

这里也要注意一点，Swagger2 中的接口访问地址是：

http://localhost:28080/sms/swagger-ui.html

这里 Swagger2 和 Swagger3 是不同的，这里大家一定要注意，否则可能你继续拿着 Swagger2 接口访问地址来放到 Swagger3 项目中不适用。

Swagger2 VS Swagger3

经过上面的步骤，我们就完成了 Spring Boot 集成 Swagger3 的实例测试了，而经过对比，也总结出了 Swagger2 和 Swagger3 的区别主要体现在如下几个方面：

所需依赖不同，Swagger2 需要添加两个依赖，而 Swagger3 则只需要添加一个依赖；
启用 Swagger 的注解不同，不知道大家有没有发现，无论是 Swagger2 还是 Swagger3 中的配置类，其实都是有一个注解用来启用 Swagger 的，不同之处在于 Swagger2 中用的是 @EnableSwagger2，而 Swagger3 中则用的是 @EnableOpenApi；
文档摘要信息（Docket）文件类型不同，可以发现在 Swagger 的配置类中，Swagger2 用的是 SWAGGER_2，而 Swagger3 中则用的是 OAS_3；
Swagger UI 访问地址不同，在 Swagger2 中，如果我们要访问文档地址，需要访问 http://localhost:8080/swagger-ui.html，而在 Swagger3 中，则是访问 http://localhost:8080/swagger-ui/index.html；

参考:https://blog.csdn.net/github_39655029/article/details/122386870