SpringBoot集成Swagger

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

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

引入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",
"603005981@qq.com",//作者
"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",
"603005981@qq.com",//作者
"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的。

以上。