【实战场景】SpringBoot整合Swagger快速实现

开篇词：

最近新启用了一个微服务需要接入swagger，下面就一起探讨下接入过程吧

干货篇：

一. Swagger简介

• 开源工具集： Swagger是一个包含多种工具和库的开源项目，用于支持RESTful API的设计、开发、文档化和测试。
• 标准化： Swagger通过Swagger Specification（现为OpenAPI Specification）定义了一套标准化的API描述格式，使得API的文档和描述具有一致性和可重用性。
• 多版本： 在SpringBoot中，Spring 基于Swagger 的标准/规范，开发了一套适用于Spring生态的接口工具框架 Springfox-swagger ，Swagger发展到今天，已经有2.x和3.x两种主流的大版本，同样Springfox-swagger也有两种相应的版本，两种版本略有不同，我们这里主要讲Swagger3的整合与使用。

二. SpringBoot整合Swagger3环境搭建

1. 引入maven依赖

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

2. YML配置

spring boot 2.6.x或更高版本集成Swagger时，直接运行会出现异常信息报错（空指针），主要原因是：Spring Boot 2.6及 更高版本使用的默认路径匹配规则是PathPatternMatcher，而Springfox使用的路径匹配是基于AntPathMatcher的。

所以这里需要更改一下SpringBoot配置。

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

3. Swagger配置类

配置类中各部分配置的含义都已经通过注释说明

@Configuration //声明配置类
@EnableOpenApi //开启swagger支持
public class SwaggerConfig {
   
 
    /**
     * Docket类是Swagger的配置类，要自定义修改Swagger的默认配置信息，我们需要覆盖该对象
     * @return
     */
    @Bean
    public Docket docket(){
   
                //1.以OAS_30标准构建Docket配置类
        return new Docket(DocumentationType.OAS_30)
                //2.配置Swagger接口文档基本信息apiInfo
                .apiInfo(apiInfo())
                //3.select方法开启配置扫描接口的Builder
                .select()
                //4.指定要扫描/维护接口文档的包（否则就全部扫描）
                .apis(RequestHandlerSelectors.basePackage("com.example.bootswagger.controller"))
                //5.路径过滤：该Docket-UI展示时，只展示指定路径下的接口文档(any表示都展示)
                .paths(PathSelectors.any())
                .build();
    }
 
    /**
     * 配置 Swagger 接口文档的基本信息
     * @return
     */
    private ApiInfo apiInfo(){
   
        return new ApiInfoBuilder()
                //1.接口文档标题
                .title("SpringBoot整合Swagger")
                //2.接口文档描述内容
                .description("这里是SpringBoot整合Swagger的详细信息......，包括...")
                //3.项目文档迭代版本
                .version("9.0")
                //4.主要联系人信息（姓名name，个人主页url，邮箱email）
                .contact(new Contact("阿安","www.baidu.com","1436218372@qq.com"))
                //5.相关许可证信息
                .license("The 优快云 License")
                //6.相关许可证链接
                .licenseUrl("www.baidu.com")
                //7.返回构建的ApiInfo对象
                .build();
    }
}

    配置完成后启动SpringBoot项目，访问 http://localhost:8080/swagger-ui/index.html 或 http://localhost:8080/swagger-ui/ 即可看到生成的接口文档。

4. Swagger分组配置

    在Swagger实现中，一个Docket配置类对应一组文档配置，既然要进行分组，那么分几组我们就要分别配置几个相应的Docket对象，然后通过