Spring boot集成swagger2

一、Swagger2是什么？

Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。

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

　　官网：http://swagger.io/

　　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，应该可以帮助大家在一定程度上提高工作效率的。最后，留一个问题给大家思考吧，就是该文档是可以直接通过页面来访问的，那我们总不能把接口直接暴露在生产环境吧，尤其是要对外提供服务的系统，那我们怎么才能在生产环节中关闭这个功能呢？方法有很多，大家可以自己尝试一下。