一、Swagger2是什么？
Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。
GitHub地址：https://github.com/swagger-api/swagger-ui
二、Swagger2与Spring boot集成
第一步，引入maven依赖
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.7.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.7.0</version> </dependency>
第二歩，基本信息配置
@Configuration
@EnableSwagger2
public class Swagger2Config {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.ybz.third"))
.paths(PathSelectors.regex("/third/.*"))
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("友报账第三方Spring Boot项目中构建RESTful APIs")
.description("友报账订单中心")
.termsOfServiceUrl("http://127.0.0.1:8080/")
.contact("马振全")
.version("1.0")
.build();
}
}
基础的配置是对整个API文档的描述以及一些全局性的配置，对所有接口起作用。这里涉及到两个注解：
@Configuration是表示这是一个配置类，是JDK自带的注解，前面的文章中也已做过说明。
@EnableSwagger2的作用是启用Swagger2相关功能。
在这个配置类里面我么实例化了一个Docket对象，这个对象主要包括三个方面的信息：
（1）整个API的描述信息，即ApiInfo对象包括的信息，这部分信息会在页面上展示。
（2）指定生成API文档的包名。
（3）指定生成API的路径。按路径生成API可支持四种模式，这个可以参考其源码：
public class PathSelectors {
private PathSelectors() {
throw new UnsupportedOperationException();
}
public static Predicate<String> any() {
return Predicates.alwaysTrue();
}
public static Predicate<String> none() {
return Predicates.alwaysFalse();
}
public static Predicate<String> regex(final String pathRegex) {
return new Predicate<String>() {
public boolean apply(String input) {
return input.matches(pathRegex);
}
};
}
public static Predicate<String> ant(final String antPattern) {
return new Predicate<String>() {
public boolean apply(String input) {
AntPathMatcher matcher = new AntPathMatcher();
return matcher.match(antPattern, input);
}
};
}
}
从源码可以看出，Swagger总共支持任何路径都生成、任何路径都不生成以及正则匹配和ant 模式匹配四种方式。大家可能比较熟悉的是前三种，最后一种ant匹配，如果不熟悉ant的话就直接忽略吧，前三种应该足够大家在日常工作中使用了。
Spring boot项目中的例子：
@RestController
public class HelloWorldController {
@Autowired
IUserService userService;
@RequestMapping(value = "/hello/world", method = RequestMethod.POST)
public String index() {
return "Hello World";
}
@RequestMapping(value = "/hello/getUser", method = RequestMethod.GET)
public User getUser() {
return userService.selectByPrimaryKey(1);
}
@RequestMapping(value = "/test/getUser", method = RequestMethod.GET)
public User test() {
return userService.selectByPrimaryKey(1);
}
}
启动Spring boot，然后访问：http://127.0.0.1:8080/swagger-ui.html即可看到如下结果：
这个页面上可以看到，除了最后一个接口/test/getUser外，其他接口都生成对应的文档，最后一个接口因为不满足我们配置的路径——“/hello/.*”，所以没有生成文档。
我们还可以点进去看一下每一个具体的接口，我们这里以“POST /hello/world”这个接口为例：
三、Swagger API详细配置
不过大家看到这里肯定会有点疑问：
第一个问题：这个返回结果和请求参数都没有文字性的描述，这个可不可以配置？
第二个问题：这个请求参应该是直接根据对象反射出来的结果，但是不是对象的每个属性都是必传的，另外参数的值也不一定满足我们的需求，这个能否配置？
答案肯定是可以的，现在我们就来解决这两个问题，直接看配置的代码：
@ApiOperation(value = "你好世界", notes = "测试swagger2", tags = "hello",httpMethod = "POST")
@ApiImplicitParams({
@ApiImplicitParam(name = "world", value = "请求内容", required = true, dataType = "String"),
})
@RequestMapping(value = "/hello/world", method = RequestMethod.POST)
public String index(@RequestBody String world) {
return "Hello "+world;
}
我们解释一下代码中几个注解及相关属性的具体作用：
@ApiOperation，整个接口属性配置：
value：接口说明，展示在接口列表。
notes：接口详细说明，展示在接口的详情页。
tags：接口的标签，相同标签的接口会在一个标签页下展示。
httpMethod：支持的HTTP的方法。
@ApiImplicitParams，@ApiImplicitParam的容器，可包含多个@ApiImplicitParam注解
@ApiImplicitParam，请求参数属性配置：
name：参数名称
value：参数说明
required：是否必须
dataType：数据类型
@ApiResponses，@ApiResponse容器，可以包含多个@ApiResponse注解
@ApiResponse，返回结果属性配置：
code：返回结果的编码。
message：返回结果的说明。
response：返回结果对应的类。
完成以上配置后，我们再看下页面效果：
我们可以从页面上看到请求参数的说明是有的，不过这不是我们预期的效果，如果我们的参数仅仅是简单类型，这种方式应该没问题，但现在的问题是我们的请求参数是一个对象，那如何配置呢？这就涉及到另外两个注解：
@ApiModel和@ApiModelProperty：
@ApiModel是对整个类的属性的配置：
value：类的说明
description：详细描述
@ApiModelProperty是对具体每个字段的属性配置：
name：字段名称
value：字段的说明
required：是否必须
example：示例值
hidden：是否显示
操作还是很方便的，相比Junit和postman，通过Swagger来测试会更加便捷，当然，Swagger的测试并不能代替单元测试，不过，在联调的时候还是有非常大的作用的。
四、总结
总体上来说，Swagger的配置还是比较简单的，并且Swagger能够自动帮我们生成文档确实为我们节省了不少工作，对后续的维护也提供了很大的帮助。
除此之外，Swagger还能根据配置自动为我们生成测试的数据，并且提供对应的HTTP方法，这对我们的自测和联调工作也有不少的帮助，所以我还是推荐大家在日常的开发中去使用Swagger，
应该可以帮助大家在一定程度上提高工作效率的。
最后，留一个问题给大家思考吧，就是该文档是可以直接通过页面来访问的，那我们总不能把接口直接暴露在生产环境吧，尤其是要对外提供服务的系统，那我们怎么才能在生产环节中关闭这个功能呢？
方法有很多，大家可以自己尝试一下。