Swagger – The World’s Most Popular Framework for APIs
Swagger是一套规范和完整的框架用于生成、描述、调用和可视化RESTful风格的Web服务

1.集成

* 添加依赖:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-annotations</artifactId>
<version>2.8.5</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.8.5</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-core</artifactId>
<version>2.8.5</version>
</dependency>
<dependency>
<groupId>com.mangofactory</groupId>
<artifactId>swagger-springmvc</artifactId>
<version>1.0.2</version>
</dependency>

* 集成Swagger-UI:

https://github.com/swagger-api/swagger-ui 获取其所有的 dist 目录下东西放到需要集成的项目里,本文放入 src/main/webapp/api/ 目录下

2.编写Swagger代码

* 编写config

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
package com.yiwei.api.apidoc;
import com.mangofactory.swagger.configuration.SpringSwaggerConfig;
import com.mangofactory.swagger.models.dto.ApiInfo;
import com.mangofactory.swagger.plugin.EnableSwagger;
import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
/**
* Created by Melon on 17/2/14.
*/
@Configuration
@EnableWebMvc
@EnableSwagger
@ComponentScan("com.yiwei.api.apidoc")
public class SwaggerConfig {
private SpringSwaggerConfig springSwaggerConfig;
/**
* Required to autowire SpringSwaggerConfig
*/
@Autowired
public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
this.springSwaggerConfig = springSwaggerConfig;
}
/**
* Every SwaggerSpringMvcPlugin bean is picked up by the swagger-mvc
* framework - allowing for multiple swagger groups i.e. same code base
* multiple swagger resource listings.
*/
@Bean
public SwaggerSpringMvcPlugin customImplementation() {
return new SwaggerSpringMvcPlugin(this.springSwaggerConfig).apiInfo(
apiInfo()).includePatterns(".*");
}
private ApiInfo apiInfo() {
ApiInfo apiInfo = new ApiInfo("万境API",
"万境API", "开发者: Melon",
"leejavalife@gmail.com", "MIT License", "/LICENSE");
return apiInfo;
}
}

* 编写API描述注解说明

1
2
3
4
5
6
7
8
9
10
@ResponseBody
@RequestMapping(value = "/list", produces = "application/json;charset=UTF-8", method = {
RequestMethod.POST, RequestMethod.GET})
@ApiOperation(value = "根据页码获取活动列表", httpMethod = "GET", response = Activity.class, notes = "页码起始值为0")
@ApiResponses(value = {@ApiResponse(code = 405, message = "Invalid input", response = Activity.class), @ApiResponse(code = 401, message = "No data", response = Result.class)})
public String list(@ApiParam(required = true, value = "页码")
@RequestParam(value = "page", required = false, defaultValue = "0") int page) {
}

3.部署

<mvc:resources mapping="/api/**" location="/api/" />

4.使用感受

优点:

  1. 集成简单,上手快
  2. 无需手动再去维护一份API接口的Word或者Excel文档
  3. 永远与接口内容的版本保持一致,方便团队协作

缺点:

  1. 后端开发者工作内容量增加
  2. 无法根据测试内容生成统一格式的测试记录
  3. 对于技术基础比较薄弱的非技术人员有一定门槛
  4. 无法在文档中对于接口内容做动态处理(标记Bug问题之类)

TO DO:

  1. 简化Swagger的内容描述编写工作
  2. 增强文档的互动性和可扩展性
  3. 针对文档内容进行自动化测试并生成测试报告
  4. 根据目前Swagger的优缺点完善优化PowerAPI(http://www.powerapi.cn