Spring Boot集成Swagger2

---

1.什么是Swagger2

Swagger 是一种接口描述语言，主要用于生成、描述、调用以及可视化 RESTful 风格的 Web 服务接口文档。
以前的项目可能更多的是前后端未分开同时进行开发，所以接口文档可能不是那么重要。
但现在主流的项目基本都是前后端分离，如果前后端没有沟通好，就有可能导致接口文档更新不及时，造成一些不必要的麻烦。
而通俗地讲，Swagger 就是帮我们写接口文档的。它不仅能自动生成实时接口文档，还能生成测试用例，方便我们进行测试。

官网：https://swagger.io/
Maven 仓库：

2.SpringBoot集成Swagger2

导入Maven依赖

   <!-- swagger2核心 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>3.0.0</version>
        </dependency>
        <!-- swagger2的UI界面 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>3.0.0</version>
        </dependency>

创建config包，编写配置类

package com.blog.demo.config;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration  //定义配置类 @Component交由spring管理Bean
@EnableSwagger2 //开启Swagger2
public class Swagger2config {
}

启动springboot项目，报错
原因： 这是因为Springfox使用的路径匹配是基于AntPathMatcher的，而Spring Boot 2.6.X使用的是PathPatternMatcher。
查了一下百度说添加以下配置

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

结果报404,；
所以选择回退版本选择使用人数较多的2.9.2版本，还是报错，加入上面的配置后，这次运行成功，并且也可以访问到页面：
http://localhost:8080/swagger-ui.html
因为使用的是 @RequestMapping注解，没有指定访问的请求类型，所以接口都显示了

3.Swagger2配置管理

配置Swagger2是通过实体类Docket进行操作的

swagger信息类

(1)对Swagger2信息进行更改

@Configuration  //定义配置类 @Component交由spring管理Bean
@EnableSwagger2 //开启Swagger2
public class Swagger2config {
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }
    private ApiInfo apiInfo() {
        Contact DEFAULT_CONTACT = new Contact("刘恒", "https://www.baidu.com/", "2296273390@qq.com");
       return new ApiInfo("恒哥的接口文档",
                "博客系统的api文档",
                "1.0",
                "urn:tos",
                DEFAULT_CONTACT,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

(2)swagger配置扫描接口

slelect底层new ApiSelectorBuilder（）
apios可以发现只有一个

public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
        //RequestHandlerSelectors,配置要扫描接口的方式
        //basePackage指定扫描的包
        //any扫描全部的包
        //none()都不扫描
        //withClassAnnotation()扫描类上的注解，参数是注解的反射对象
        //withMethodAnnotation()扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.blog.demo.controller"))
                .build();

 .apis(RequestHandlerSelectors.basePackage("com.blog.demo.controller"))
                //paths是过滤路径，不让com.blog.demo的过去
                //   any()任何请求都扫描
                //none()  任何请求都不扫描
                //regex(final String pathRegex) 通过正则表达式控制，返回true扫描，false不扫描
                // ant(final String antPattern)通过ant()表达式控制，返回true扫描，false不扫描
                .paths(PathSelectors.ant("com.blog.demo"))
                .build();

(3)配置api文档分组（分组无非就是多个Docket）

  @Bean
    public Docket docket1(){
        return  new Docket(DocumentationType.SWAGGER_2).groupName("开发者1");
    }
    @Bean
    public Docket docket2(){
        return  new Docket(DocumentationType.SWAGGER_2).groupName("开发者2");
    }
    @Bean
    public Docket docket3(){
        return  new Docket(DocumentationType.SWAGGER_2).groupName("开发者3");
    }

(4)实体类的配置

只要返回值中存在实体类，他就会被扫描到Swagger中

对实体类增加注释说明：

• @ApiModel(“ ”)为实体类添加说明信息
• @ApiModelProperty(“ ”)为实体类中的属性添加说明信息
• @Api(tags = “ ”)为接口添加说明信息
• @ApiOperation(“ ”)为请求增加说明信息
• @ApiParam(“ ”)为请求中的参数增加说明信息

@ApiModel("管理员类")
public class User {
    private Integer id;
    @ApiModelProperty("管理员用户名")
    private  String username;

@Controller
@Api(tags = "管理员登录接口")
public class loginController {
    private Logger logger = LoggerFactory.getLogger(loginController.class);

    @Autowired
    private AdminServiceImpl adminService;
    @ApiOperation("得到管理员信息请求")
    @GetMapping("/app")
    @ResponseBody
    public User getUser(){
        User user = adminService.queryAdmin();
        return  user;
    }
    @GetMapping("/hello")
    public String hello(@ApiParam("请求参数中的name") String username){
        return "hello"+username;
    }
}

面试题：如果我们希望Swagger在某一个环境中使用，在其他时候不使用怎么办

第一种方法：Environment

public class Swagger2config {
    @Resource
    private  Environment environment;
    @Bean
    public Docket docket(){
        Profiles profiles = Profiles.of("dev");
       //获取生产环境
       //通过environment.acceptsProfiles(profiles)判断自己是否处在指定环境
        boolean isEnable = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(isEnable)
                .select()
               .apis(RequestHandlerSelectors.basePackage("com.blog.demo.controller"))
                .build();
    }

spring:
  profiles:
    active: pro

第二种方法：通过@Value注解获取，进行if判断即可：

   private org.slf4j.Logger logger = LoggerFactory.getLogger(Swagger2config.class);
    @Value("${spring.profiles.active}")
    private  String active;
    @Bean
    public Docket docket(){
         //打印在控制台上:
        logger.info("生产环境是"+active);