SpringBoot教程（十七） | SpringBoot集成Swagger系列（版本2、版本3）

一、Swagger的简述

Swagger（现在更广泛地被称为OpenAPI）是一套基于OpenAPI规范构建的开源工具，它主要用于生成、描述、调用和可视化RESTful风格的Web服务。
其中最重要的表现在于实时接口文档，可以更好的让前端进行联调

二、SpringBoot集成swagger2

1. 引入依赖

首先，你需要在项目的pom.xml文件中添加Swagger2的依赖。

<dependencies>  
    <!-- Swagger2 -->  
    <dependency>  
        <groupId>io.springfox</groupId>  
        <artifactId>springfox-swagger2</artifactId>  
        <!-- 注意：这里使用的是2.9.2版本 用的人比较多 -->  
        <version>2.9.2</version> 
    </dependency>  
    <dependency>  
        <groupId>io.springfox</groupId>  
        <artifactId>springfox-swagger-ui</artifactId>  
        <!-- 与swagger2版本保持一致 -->  
        <version>2.9.2</version> 
    </dependency>  
</dependencies>

2. 新建SwaggerConfig配置类

@EnableSwagger2

@Configuration  
@EnableSwagger2  
public class SwaggerConfig {  
    @Bean  
    public Docket docket() {  
        return new Docket(DocumentationType.SWAGGER_2)  
                .select()  
                //通过包路径来指定哪些Controller中的API需要被Swagger扫描并生成文档。
                //这里指定了"com.yourcompany.yourproject.controller"包及其子包中的所有Controller。
                .apis(RequestHandlerSelectors.basePackage("com.yourcompany.yourproject.controller"))  
                //扫描所有路径  
                .paths(PathSelectors.any()) 
                .build()  
                 //设置API的元数据信息，如标题、描述、版本等。
                 //这些信息会显示在Swagger UI的顶部。   
                .apiInfo(apiInfo());
    }  
  
    private ApiInfo apiInfo() {  
        return new ApiInfoBuilder()  
                .title("你的项目名称")  
                .description("项目的API描述")  
                .version("1.0")  
                .build();  
    }  
}

如果你只想包含特定路径的API，可以使用其他PathSelectors方法，
如antPath(“/user/**”)来匹配所有以"/user/"开头的路径。

可以把 .paths(PathSelectors.any())  换成 .paths(PathSelectors.antPath("/user/**"))

当 SpringBoot为2.6.x及以上时 需要注意

由于SpringBoot 2.6.x及以上版本使用了新的路径匹配策略（PathPatternMatcher），
而Swagger（尤其是Springfox-swagger2）通常使用的是AntPathMatcher，
这可能会导致两者之间的不兼容问题。

在application.properties或application.yml文件中，
可以将SpringBoot的默认路径匹配策略更改为AntPathMatcher，以解决与Swagger的兼容性问题。
配置示例如下：

properties写法如下

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

或者在application.yml中：

spring:  
  mvc:  
    pathmatch:  
      matching-strategy: ant_path_matcher

3.配置Swagger开关

可以在application.properties或application.yml文件中定义不同的环境配置，
然后在Swagger配置类中根据当前激活的Profile来决定是否启用Swagger。

application.yml示例：

spring:  
  profiles: 
    #指定激活 
    active: dev  
  
--- 
#测试环境 
spring:  
  config:  
    activate:  
      on-profile: dev  
swagger:  
  enabled: true  
  
---  
#开发环境
spring:  
  config:  
    activate:  
      on-profile: prod  
swagger:  
  enabled: false

@Configuration  
@EnableSwagger2  
public class SwaggerConfig {  
  
    // 使用@Value注解读取配置文件中的swagger.enabled值  
    @Value("${swagger.enabled:false}")  
    private Boolean swaggerShow;  
  
    @Bean  
    public Docket docket() {  
        return new Docket(DocumentationType.SWAGGER_2)  
                .enable(swaggerShow)
                .select()  
                // 通过包路径来指定哪些Controller中的API需要被Swagger扫描并生成文档  
                .apis(RequestHandlerSelectors.basePackage("com.yourcompany.yourproject.controller"))  
                // 扫描所有路径  
                .paths(PathSelectors.any())  
                .build()  
                // 设置API的元数据信息  
                .apiInfo(apiInfo());   
    }  
  
    private ApiInfo apiInfo() {  
        return new ApiInfoBuilder()  
                .title("你的项目名称")  
                .description("项目的API描述")  
                .version("1.0")  
                .build();  
    }  
}

4. 在你的Controller上添加swagger注解

import com.mcy.springbootswagger.User.User;
import com.mcy.springbootswagger.service.UserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/user")
//说明接口文件
@Api(value = "测试接口", tags = "用户管理相关的接口", description = "用户测试接口")
public class UserController {
    @Autowired
    private UserService userService;

    /**
     * 保存数据
     * @param user
     * @return
     */
    @PostMapping(value = "/save")
    //方法参数说明，name参数名；value参数说明，备注；dataType参数类型；required 是否必传；defaultValue 默认值
    @ApiImplicitParam(name = "user", value = "新增用户数据")
    //说明是什么方法(可以理解为方法注释)
    @ApiOperation(value = "添加用户", notes = "添加用户")
    public String saveUser(User user){
        userService.save(user);
        return "保存成功";
    }

    /**
     * 根据id查询用户
     * @param id
     * @return
     */
    @GetMapping(value = "findById")
    @ApiOperation(value = "根据id获取用户信息", notes = "根据id查询用户信息")
    public User getUser(Integer id){
        return userService.findById(id);
    }

    @DeleteMapping(value = "deleteById")
    @ApiOperation(value = "根据id删除数据", notes = "删除用户")
    public String delete(Integer id){
        userService.deleteById(id);
        return "删除成功";
    }
}

5. 启动应用，访问 ip:端口/swagger-ui.html （默认皮的情况下）

运行项目，输入http://localhost:8080/swagger-ui.html 访问Swagger页面，页面如下：

由于我们只给用户接口添加了注解，所有用户接口是可以直接观察中文文档的。

• 点击需要测试的接口方法后，
  可以看到接口需要的参数，请求地址及接口说明信息。
  点击右上角的Try it out即可对接口进行测试。
  
  
• 查询结果：
  
  这里这些了部分接口进行测试，可以根据项目需求自行添加其他接口。

6. SpringSecurity中配置 （看需求使用）

如果Spring Boot项目中集成了Spring Security，接口会被拦截，需要在Spring Security的配置类中重写configure方法，对接口进行过滤一下。代码如下：

@Override
public void configure(WebSecurity web) throws Exception {
    web.ignoring()
            .antMatchers("/swagger-ui.html")
            .antMatchers("/v2/**")
            .antMatchers("/swagger-resources/**");
}

三、SpringBoot集成swagger3

Swagger3在Swagger2的基础上进行了部分升级， 使用和Swagger2没有多少区别。
一个重要的优化是依赖的引入，由之前的多个依赖变更为一个依赖，跟随springboot-starter风格，同时引入了新的开关注解 @EnableOpenApi 以代替@EnableSwagger2 。
因此，集成工作变得更加的简便了，必要工作只有两个，添加swagger3的starter依赖包，在springboot主程序类添加@EnableOpenApi开关注解。

1. 引入依赖 springfox-boot-starter

<!-- 引入Swagger3依赖 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

2. 新建SwaggerConfig配置类

然后是替换注解： swagger2使用的开启注解是： @EnableSwagger2
而在swagger3中，这个注解要换成： @EnableOpenApi

/**
* Swagger配置类
*/
@Configuration
@EnableOpenApi
public class SwaggerConfig {
    @Bean
    public Docket docket(){
      // 构造方面里面的对象 和v2的不一样
       return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .enable(true)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example"))
                .paths(PathSelectors.any())
                .build();
    }
    
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("XX项目接口文档")
                .description("XX项目描述")
                .contact(new Contact("作者", "作者URL", "作者Email"))
                .version("1.0")
                .build();
    }
}

3. 在你的Controller上添加swagger注解

@Api(tags="用户管理")
@RestController
@RequestMapping("/user")
public class UserController {

    @ApiOperation("用户列表")
    @GetMapping("/{id}")
    public JsonResult getViewObjectMapping(@PathVariable("id") Long id) throws Exception{
        return super.getViewObject(id, UserVO.class);
    }

}

4. 启动应用，访问 ip:端口/swagger-ui/index.html （默认皮的情况下）

访问地址和v2版本有点不一样了，改为 localhost:8080/swagger-ui/index.html 了。

参考文章
【1】SpringBoot之整合Swagger2(完整版)
【2】SpringBoot整合Swagger2（完整版）
【3】SpringBoot教程(十六) | SpringBoot集成swagger（全网最全）
【4】springboot 2.7版本整合swagger2代码实现
【5】【Swagger】maven项目整合Swagger（含Springfox3.0与spring boot 2.6.0及以上版本冲突解决办法）
【6】一篇搞定SpringBoot任意版本集成Swagger各种版本