详解SpringBoot整合Swagger2附带验证Token功能

背景

当开发的项目前后端分离后，维护接口文档基本上是必不可少的工作。但是实际开发过程中，接口总是在不断的变化，有变化就要去维护，做过的同志们都知道这件事有多么头大！但是现在有困难就解决困难，在这样的背景下，有一些工具可以减轻我们的工作量，Swagger2就是其中之一。本文主要是关于Spring Boot中如何整合Swagger2。

依赖引入

在pom.xml引入Swagger相关的依赖，依赖如下：

<!-- Swagger -->
		<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>
<!-- End Swagger -->

创建Swagger配置类

在Swagger配置类，开发者自己提供一个Docket的Bean即可。

@Configuration
@EnableSwagger2
public class Swagger2Config {

    // swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等
    @Bean
    public Docket createRestApi() {
    //一些项目设计Token验证，如果你的项目不存在Token验证这里可以忽略
        ParameterBuilder tokenPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<>();
        tokenPar.name("Authorization").description("令牌").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
        pars.add(tokenPar.build());

        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                // 扫描包路径
                .apis(RequestHandlerSelectors.basePackage("这里填写你的接口路径"))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(pars)
                .apiInfo(apiInfo());
    }
    
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("*********")
                //详细描述
                .description("API 描述")
                .termsOfServiceUrl("https://blog.csdn.net/zjt11112?spm=1001.2101.3001.5343")
                .version("1.0")
                .license("Jeter")
                .build();
    }
}

接口类示例

实际接口看自己情况，主要需要注意的是@Api注解放在类上，@ApiOperation注解放在方法上。

@Api(value="Test API",tags={"Test API"})
@RestController
public class TestController {
    @PostMapping("/test")
    @ApiOperation(value = "接口的功能介绍", notes = "提示接口使用者注意事项")
    public Result Test(@RequestBody User user) {

      return ResultGenerator.genSuccessResult("success");
    }
}

示例图如下：

启用Swagger

第一种方式：自动类加注解

@SpringBootApplication
@EnableSwagger2
public class SwaggerTestApplication{
 public static void main(String[] args) {
        SpringApplication.run(OutlookparserApplication.class, args);
    }
}

第二种方式：配置文件设置启用

swagger2.enable=true

总结：个人认为第二种方式更加灵活，推荐使用第二种。因为并不是所有环境都允许使用Swagger，比如PROD环境，第二种方式只需要写在配置文件里无需修改代码。

原创不易，求个点赞！