SpringBoot集成Swagger

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

这里介绍一下spring boot和swagger基本的集成：

1. 引入jar

<!--Swagger-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.4.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.4.0</version>
</dependency>

springfox的前身是springmvc-swagger这样的一个框架（大概是这个名字），都是做springMVC和swagger集成的。

2.Swagger配置

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.context.request.async.DeferredResult;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import static com.google.common.base.Predicates.or;
import static springfox.documentation.builders.PathSelectors.regex;

/**
 * author: FrancisZ
 * time: 16/5/6
 */
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

    @Value("${swagger.show}")
    private boolean swaggerShow;

    /**
     * 可以定义多个组，比如本类中定义把test和demo区分开了
     * （访问页面就可以看到效果了）
     *
     */
    @Bean
    public Docket testApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(this.swaggerShow)
                .groupName("test")
                .genericModelSubstitutes(DeferredResult.class)
//                .genericModelSubstitutes(ResponseEntity.class)
                .useDefaultResponseMessages(false)
                .forCodeGeneration(true)
                .pathMapping("/")// base，最终调用接口后会和paths拼接在一起
                .select()
                .paths(or(regex("/test/.*")))//过滤的接口
                .build()
                .apiInfo(testApiInfo());
    }

    @Bean
    public Docket demoApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(this.swaggerShow)
                .groupName("demo")
                .genericModelSubstitutes(DeferredResult.class)
//              .genericModelSubstitutes(ResponseEntity.class)
                .useDefaultResponseMessages(false)
                .forCodeGeneration(false)
                .pathMapping("/")
                .select()
                .paths(or(regex("/demo/.*")))//过滤的接口
                .build()
                .apiInfo(demoApiInfo());
    }

    private ApiInfo testApiInfo() {
        ApiInfo apiInfo = new ApiInfo("IAP API",//大标题
                "Internal Application Platform.",//小标题
                "0.1",//版本
                "NO terms of service",
                "[email protected]",//作者
                "The Apache License, Version 2.0",//链接显示文字
                "http://www.apache.org/licenses/LICENSE-2.0.html"//网站链接
        );

        return apiInfo;
    }

    private ApiInfo demoApiInfo() {
        ApiInfo apiInfo = new ApiInfo("IAP API",//大标题
                "Internal Application Platform.",//小标题
                "0.1",//版本
                "NO terms of service",
                "[email protected]",//作者
                "The Apache License, Version 2.0",//链接显示文字
                "http://www.apache.org/licenses/LICENSE-2.0.html"//网站链接
        );

        return apiInfo;
    }
}

这部分我也没有深究，具体每部分内容对应页面上那些部分，多试试吧。

3.MVC Configuration

/**
 * author: FrancisZ
 * time: 16/4/5
 */
@Configuration
public class MVCConfiguration extends WebMvcConfigurerAdapter {
    @Value("${swagger.show}")
    private boolean swaggerShow;

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        if (this.swaggerShow) {
            registry.addResourceHandler("swagger-ui.html")
                    .addResourceLocations("classpath:/META-INF/resources/");

            registry.addResourceHandler("/webjars/**")
                    .addResourceLocations("classpath:/META-INF/resources/webjars/");
        }
    }
}

这边添加的两个ResourceHandler主要是指定swagger ui的地址，不然的话无法访问swagger的页面。

4.添加一个简单的API

@RequestMapping(value = "/Permission/list/Role/{roleId}", produces = "application/json;charset=utf-8", method = RequestMethod.GET)
    @ResponseBody
    @ApiOperation(value = "获取角色权限", httpMethod = "GET", response = String.class, notes = "获取角色的所有权限")
    @ApiParam(required = true, name = "roleId", value = "角色ID")
    public String getRolePermissions(@PathVariable("roleId") Integer roleId) {
        Iterable<PermissionDto> permissionDtoList = this.permissionService.getByRole(roleId);
        Map<String, Object> resultMap = new HashMap<String, Object>();
        resultMap.put("code", "0");
        resultMap.put("data", permissionDtoList);
        String result = JSONObject.toJSONString(resultMap);
        return result;
    }

这里主要是两个注解，@ApiOperation和@ApiParam。可以看出来一个是对API的描述，一个是对API参数的描述。

@ApiIgnore注解标明这个API不想被swagger处理，默认情况下只要被@RequestMapping注解的方法都会被生成文档（没有详细测试）。

5.Swagger路由问题

Swagger带来的好处是巨大的，但是在生产环境并不需要看到接口文档，这反倒有一些安全问题。对于这个问题，第一反应是加权限，不过仔细想想的话，即使是在校验了权限之后，在生产环境也不应该看到接口文档。而且加权限的话还需要其他的工作量。

这里提供的一个办法是通过配置参数，控制Swagger路由。在Spring Boot的配置文件中添加swagger.show这个参数，只有当值为true的时候才生成swagger的路由，以及让swagger初始化（具体做法可以参考上面第2，3两步中swaggerShow这个参数的使用）。测试下来，这个办法是能比较彻底屏蔽Swagger的。

以上。