Springboot中使用Swagger2构建RESTful API文档

Swagger 简介

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

官网 ： swagger.io

在springboot中使用Swagger

Swagger可以轻松的整合到Spring Boot中，并与Spring MVC程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的工作量，同时说明内容又整合入实现代码中，让维护文档和修改代码整合为一体，可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API。

添加Swagger2的相关依赖

pom.xml ：

<!--Swagger2-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.2.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.2.2</version>
        </dependency>

创建Swagger2配置类

在springboot启动类的同级目录下创建Swagger2的配置类Swagger2：

public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.echo0.springboot.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Demo API docs")
                .description("http://blog.echo0.cn/")
                .termsOfServiceUrl("http://blog.echo0.cn/")
                .contact("Echo0")
                .version("0.9")
                .license("The Apache License, Version 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
                .build();
    }
}

如上代码所示，通过@Configuration注解，让Spring来加载该类配置。再通过@EnableSwagger2注解来启用Swagger2。

再通过createRestApi函数创建Docket的Bean之后，apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，本例采用指定扫描的包路径来定义，Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore指定的请求）。

添加文档内容

在完成了上述配置后，其实已经可以生产文档内容，但是这样的文档主要针对请求本身，而描述主要来源于函数等命名产生，对用户并不友好，我们通常需要自己增加一些说明来丰富文档内容。如下所示，我们通过@ApiOperation注解来给API增加说明、通过@ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明。

@ApiOperation(value = "查找用户", notes = "根据person对象名称来查找")
@ApiImplicitParams({@ApiImplicitParam(name = "name", value = "用户名",
        required = true, dataType = "String",paramType = "path" )
})
@GetMapping("/query/{name}")
public List<Person> addPersonEntity(
        @PathVariable("name") String name) {

    return personRepository.findByName(name);

}

需要注意paramType这个属性,该属性指定了参数的类型（不如说是来源），上面的代码中指定了paramType = "path",表示参数应来自于url路径。该属性的说明如下：

/**
 * The parameter type of the parameter.
 * <p/>
 * Valid values are {@code path}, {@code query}, {@code body}, {@code header} or {@code form}.
 */
String paramType() default "";

查看效果

启动springboot 程序，访问 http://localhost:portNum/projectRootPath/swagger-ui.html便可以看到效果：

Swagger除了查看接口功能外，还提供了调试测试功能 :

输入参数，点击 try it out 按钮即可进行测试。

#### 完整示例代码

Springboot-demo