Spring Boot项目集成Swagger

参考  一篇文章带你搞懂 SpringBoot与Swagger整合  和 在 Spring Boot 项目中使用 Swagger 文档和Spring Boot中使用Swagger2构建强大的RESTful API文档

1.引入依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<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>

2.配置Swagger  

 基本配置：新建Swagger配置类。配置文档信息配置：Swagger 支持设置一些文档的版本号，联系人邮箱，网站，版权，开源协议等等信息。这些信息不是通过注解配置，而是通过创建一个ApiInfo对象，对使用Docket.appInfo()方法来设置。

import java.util.ArrayList;
import java.util.List;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;


@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {


        List<Parameter> parameters = new ArrayList<>();
        ParameterBuilder parameterBuilder = new ParameterBuilder();
        parameterBuilder.name("token").description("token").modelRef(new ModelRef("string")).parameterType("header")
                .required(false).build();//add http header parameter : token
        parameters.add(parameterBuilder.build());

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any()).build().globalOperationParameters(parameters);
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("project 实例文档")
                .description("project 实例文档 1.0")
                .termsOfServiceUrl("https:github")
                .version("1.0")
                .build();
    }

}

3.如果Springboot项目中配置了拦截器，需要在拦截器配置放行swagger 。具体配置如下

参考Springboot引入拦截器并放行swagger代码实例 和 将拦截器添加到springmvc配置中，并放行swagger的相关资源

import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
 

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Autowired
    private TokenHelper tokenHelper;

    @Override
    public void addInterceptors(InterceptorRegistry registry) {

        List<String> excludePath = new ArrayList<>();
        // 获取token 不要验证
        excludePath.add("/api/generateToken");
        //放行 swagger
        excludePath.add("/swagger-resources/**");
        excludePath.add("/webjars/**");
        excludePath.add("/v2/**");
        excludePath.add("/swagger-ui.html/**");

        registry.addInterceptor(new TokenInterceptor(tokenHelper)).addPathPatterns("/**")
                .excludePathPatterns(excludePath);
    }

 
}

 

4.看效果：重新启动一下项目，然后在浏览器中访问 http://localhost:8080/swagger-ui.html 就可以看到如下的效果了:

 

5.Swagger 注解具体使用 

5.1 通过在控制器类上增加@Api 注解，可以给控制器增加描述和标签信息。

5.2 通过在接口方法上增加 @ApiOperation 注解来展开对接口的描述 

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;

@RestController
@RequestMapping("/api")
@Api(tags = "about test")
public class TestController {

 
    @GetMapping(value = "/test")
    @ApiOperation(value = "test function")
    public void test() {
        //to do

    }
}

 

5.3 接口过滤

有些时候我们并不是希望所有的 Rest API 都呈现在文档上，这种情况下 Swagger2 提供给我们了两种方式配置，一种是基于 @ApiIgnore 注解，另一种是在 Docket 上增加筛选。这里只介绍 @ApiIgnore 注解方式。如果想在文档中屏蔽掉如下接口（/api/logdebug），那么只需要在删除用户的方法上加上 @ApiIgnore 即可。

@GetMapping(path  = "/api/logdebug")
    @ApiIgnore
    public void logdebug(@RequestParam String aa,@RequestParam String bb){
        logger.debug("====================this is /api/logdebug ====aa=="+aa);
        logger.debug("====================this is /api/logdebug ====bb=="+bb);

    }

 

5.4 实体描述，我们可以通过 @ApiModel 和 @ApiModelProperty 注解来对我们 API 中所涉及到的对象做描述

 

未写完，待补充……