参考：
http://blog.csdn.net/amon1991/article/details/76774880
http://blog.didispace.com/springbootrestfulapi/
一、为什么要用swagger2
1.手动录入API的缺点：
1）由于需求或设计的原因，并不能保证一次就可将接口确定，不再做变动，频繁的修改接口可能会导致接口文档和实际接口不一致；
2）不能直接在线测试接口，需使用其他工具，如postman
2.解决方案
swagger完美解决了以上两个问题，既能在线测试接口，又能动态生成api文档，只需在接口上加适当的备注。
3.swagger缺点
1）代码侵入性强
2）必须启动接口服务器，才能访问到接口文档
二、swagger2使用
1.添加pom依赖
添加swagger2核心包和swagger-ui界面包。
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
2.配置api文档页基本信息
与启动类同级，特别注意里面配置了API文件也就是controller的路径，不然生成的文档扫描不到接口。
@Configuration
@EnableSwagger2
public class Swagger2{
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.xx.web.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("xx项目 RESTful APIs")
.description("xx项目后台api接口文档")
.version("1.0")
.build();
}
}
spring-boot和swagger整合时，可以通过注解注入相关配置。通过这些配置可指定在spring-boot启动时扫描哪些controller层的文件夹，另外可指定api文档页的标题和描述信息等内容。
3.API文档编写示例
一般在controller层，将详尽的API接口输入输出在代码中通过注解进行相关描述。
@Api(value = "PageController", description = "用户登录登出接口")
@Controller
@RequestMapping("/")
public classPageController{
@ApiOperation(value="用户登录", notes="用户登录接口")
@ApiImplicitParams({
@ApiImplicitParam(name = "username", value = "用户名", required = true ,dataType = "string"),
@ApiImplicitParam(name = "passwd", value = "密码", required = true ,dataType = "string")
})
@RequestMapping(value = "/login",method = {RequestMethod.POST,RequestMethod.GET})
@ResponseBody
public ModelMap login(Users data, HttpServletRequest request){
xxx...
}
}
