使用Swagger2构建强大的RESTful API文档

本文将介绍RESTful API的重磅好伙伴Swagger2，它可以轻松组织出强大RESTful API文档。它既可以减少我们创建文档的工作量，同时说明内容又整合入实现代码中，让维护文档和修改代码整合为一体，可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API。

项目中整合swagger2步骤

1、添加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>
2、创建Swagger2配置类：

01 @Configuration
02 @EnableSwagger2
03 public class Swagger2Config {
04
05     @Bean
06     public Docket createRestApi() {
07
08         return new Docket(DocumentationType.SWAGGER_2)
09
10                 .apiInfo(apiInfo())
11
12                 .select()
13
14                 .apis(RequestHandlerSelectors.basePackage("com.daqsoft.ptisp.api.controller"))
15
16                 .paths(PathSelectors.any())
17
18                 .build();
19
20     }
21
22
23     /**
24      * swagger-bootstrap-ui
25      * @return
26      */
27     private ApiInfo apiInfo() {
28
29         return new ApiInfoBuilder()
30
31                 .title("swagger-bootstrap-ui RESTful APIs")
32
33                 .description("swagger-bootstrap-ui")
34
35                 .termsOfServiceUrl("http://api.test.com/")
36
37                 .contact("[e-mail]")
38
39                 .version("1.0")
40
41                 .build();
42
43     }
44
45 }

通过@Configuration注解，让Spring来加载该类配置。再通过@EnableSwagger2注解来启用Swagger2。

3、编写测试controller

01 /**
02      *  活动列表
03      * @param page
04      * @param limitPage
05      * @param siteCode
06      * @param lang
07      * @param tag
08      * @return
09      */
10     @ApiOperation(value = "活动列表", notes = "活动列表")
11     @ApiImplicitParams({
12             @ApiImplicitParam(name = "tag", value = "标签", paramType = "query"),
13             @ApiImplicitParam(name = "page", value = "当前页", defaultValue = "1", paramType = "query"),
14             @ApiImplicitParam(name = "lang", value = "语言参数", required = true, defaultValue = "cn", paramType = "query"),
15             @ApiImplicitParam(name = "limitPage", value = "每页条数", defaultValue = "10", paramType = "query"),
16             @ApiImplicitParam(name = "title", value = "文章标题", paramType = "query"),
17             @ApiImplicitParam(name = "token", value = "token", paramType = "query"),
18             @ApiImplicitParam(name = "region", value = "地区region", paramType = "query"),
19             @ApiImplicitParam(name = "siteCode", value = "站点代码", required = true, paramType = "query")
20     })
21     @RequestMapping(value = "/list", method = RequestMethod.GET)
22     public Object getList(@RequestParam(defaultValue = "1") intpage, @RequestParam(defaultValue = "10") int limitPage,
23                               String siteCode, String lang, String title, String tag, String token, String region, HttpServletRequest request) {
24         ParamValidator validator = new ParamValidator();
25         validator.notBlank(siteCode, "站点代码不能为空").notNull(lang, "语言不能为空");
26         if(validator.isValid()){
27             Site site = siteService.findOneByCodeAndLang(siteCode, lang);
28             if (null == site) {
29                 return bulidFailed("站点不存在");
30             }
31             PageData pageData = siteActivityApiService.getList(site,page,limitPage,lang,title,tag, token, region, request);
32             return pageBulidSuccess(pageData);
33         }else{
34             return bulidFailed(validator.getFailedMessage());
35         }
36     }

备注（各参数意义）：

作用范围	API	使用位置
对象属性	@ApiModelProperty	用在出入参数对象的字段上
协议集描述	@Api	用于controller类上
协议描述	@ApiOperation	用在controller的方法上
Response集	@ApiResponses	用在controller的方法上
Response	@ApiResponse	用在 @ApiResponses里边
非对象参数集	@ApiImplicitParams	用在controller的方法上
非对象参数描述	@ApiImplicitParam	用在@ApiImplicitParams的方法里边
描述返回对象的意义	@ApiModel	用在返回对象类上

@ApiImplicitParam参数：

属性	取值	作用
paramType		查询参数类型
path	以地址的形式提交数据
query	直接跟参数完成自动映射赋值
body	以流的形式提交 仅支持POST
header	参数在request headers 里边提交
form	以form表单的形式提交 仅支持POST
dataType		参数的数据类型 只作为标志说明，并没有实际验证
Long	
String	
name		接收参数名
value		接收参数的意义描述
required		参数是否必填
true	必填
false	非必填
defaultValue		默认值

4、访问效果

在浏览器输入 http://localhost:12530/doc.html，就可以调试接口。