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