springBoot集成swagger2

SpringBoot集成Swagger

Swagger主要作用就是为开发生成接口文档，方便前后端进行数据交互。通过更新Swagger的描述文件就能自动生成接口文档。
使用swagger可以直接通过代码生成接口文档，不再需要手动编写
并且提供了在线测试接口的api，参数与格式都是已经定义好的，直接在界面上传入对应的参数即可测试

swagger在与SpringBoot集成时会出现诸多问题，大概率是两者之间的版本冲突问题
我这里使用的是springBoot2.7.8，Swagger2.9.2

<!--     swagger2   -->
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.9.2</version>
</dependency>

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>2.9.2</version>
</dependency>

如果出现了错误可以尝试在SpringBoot的yaml文件中配置：spring.mvc.pathmatch.matching-strategy=ant_path_matcher

配置Swagger

对Swagger进行配置，使用配置类@Configuration

@Configuration
@EnableSwagger2 // 开启Swagger2
public class SwaggerConfig {

  // 配置swagger的Bean实例
  @Bean
  public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      ;
  }
  // 配置swagger apiInfo信息
  public ApiInfo apiInfo(){
    // 配置swagger界面展示信息  覆盖swagger的默认信息
    Contact contact = new Contact("JaThink","blog.csdn.net/yuqu1028","yuqu1028@163.com");
    return  new ApiInfo("JaThink Interface Swagger",
                        "这山高",
                        "1.0",
                        "blog.csdn.net/yuqu1028",
                        contact,
                        "Apache 2.0",
                        "http://www.apache.org/licenses/LICENSE-2.0",
                        new ArrayList());
  }
}

Swagger配置扫描接口

继续使用Docket的select和build方法来配置，如下：

// 配置swagger的Bean实例
@Bean
public Docket docket(){
  return new Docket(DocumentationType.SWAGGER_2)
    .apiInfo(apiInfo())
    // 是否开启swagger
    .enable(false)
    .select()
    // basePackage 指定扫描包
    // any 扫描全部  none  全部不扫描
    // withClassAnnotation：扫描类上的注解
    // withMethodAnnotation：扫描方法上的注解
    .apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))
    // 只扫描yuqu请求下的
    .paths(PathSelectors.ant("/yuqu/**"))
    .build()
    ;
}

设置显示swagger的环境，项目测试维护时开启swagger，项目上线时关闭swagger
可以采用SpringBoot的多环境配置，使用spring.profiles.active来指定使用哪一个yaml配置文件( 即运行环境 )

在Docket中去配置

@Bean
public Docket docket(Environment environment){
  // 配置使用swagger的环境
  Profiles profiles = Profiles.of("dev");
  // 获取项目环境
  boolean flag = environment.acceptsProfiles(profiles);
  // 如果当前环境为dev  那么就为true使用swagger  如果为false就考虑项目上线情况  不适用swagger
  return new Docket(DocumentationType.SWAGGER_2)
    .apiInfo(apiInfo())
    // 是否开启swagger
    .enable(flag)

配置API多文档分组

调用Docket对象的groupName方法入参文档名，每个分组都有自己对应的配置信息

@Bean
public Docket docket2(){
  return new Docket(DocumentationType.SWAGGER_2).groupName("第二组");
}
@Bean
public Docket docket3(){
  return new Docket(DocumentationType.SWAGGER_2).groupName("第三组");
}
@Bean
public Docket docket4(){
  return new Docket(DocumentationType.SWAGGER_2).groupName("第四组");
}

swagger2常用注解

@Api：用于类上的注解，控制整个类生成接口信息的内容。参数 tags：类名称，数组形式，可以有多个值。表示多个controllertest

@Api(tags = {"tags111","tags222"})

@ApiOperation：方法上注解，描述方法的相关信息。参数：value：方法描述、notes：方法笔记( 详细描述 )

@ApiOperation(value = "方法value",notes = "更多更多的描述")

@ApiParam：用于方法参数的注解，描述该参数。name：参数名称、value：参数作用、required：表示是否为必须参数，默认为false

public String test3(@ApiParam(name = "用户id",value = "用于查询当前用户") Integer id){