简介
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。
我们的RESTful API就有可能要面对多个开发人员或多个开发团队:IOS开发、Android开发或是Web开发等。为了减少与其他团队平时开发期间的频繁沟通成本,传统做法我们会创建一份RESTful API文档来记录所有接口细节,然而这样的做法有以下几个问题:
由于接口众多,并且细节复杂(需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等),高质量地创建这份文档本身就是件非常吃力的事,下游的抱怨声不绝于耳。
随着时间推移,不断修改接口实现的时候都必须同步修改接口文档,而文档与代码又处于两个不同的媒介,除非有严格的管理机制,不然很容易导致不一致现象。
为了解决上面这样的问题,本文将介绍RESTful API的重磅好伙伴Swagger2,它可以轻松的整合到Spring Boot中,并与Spring MVC程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的工作量,同时说明内容又整合入实现代码中,让维护文档和修改代码整合为一体,可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API。具体效果如下图所示:
添加Swagger2依赖
在pom.xml中加入Swagger2的依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.4.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.4.0</version>
</dependency>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-context</artifactId>
<version>4.3.4.RELEASE</version>
</dependency>
或者
直接导入包
注意:Spring 必须 4 以上
Jackson最好2.8
创建Swagger2配置类:
/**
* Swagger2构建RESTful APIs
* @author AndyBao
* @version 4.0, 2016年12月20日 下午2:00:30
*/
@Configuration
@EnableWebMvc
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.ybt.web.app"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("APP RESTful APIs")
.description("在线文档:http://www.xxx.xxx")
.termsOfServiceUrl("http://www.xxxx.com.cn/")
.contact("AndyBao")
.version("0.5.1")
.build();
}
}
如上代码所示,通过@Configuration注解,让Spring来加载该类配置。再通过@EnableSwagger2注解来启用Swagger2。
再通过createRestApi函数创建Docket的Bean之后,apiInfo()用来创建该Api的基本信息(这些基本信息会展现在文档页面中)。select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现,本例采用指定扫描的包路径来定义,Swagger会扫描该包下所有Controller定义的API,并产生文档内容(除了被@ApiIgnore指定的请求)。
添加文档内容
给Controller 添加注解
通过@ApiOperation注解来给API增加说明、通过@ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明。
/**
* 参数描述
*
* @param userName
* @return
*/
@RequestMapping(value = "/demo2/{userName}", method = RequestMethod.POST)
@ApiOperation(value = "测试接口2", notes = "参数描述", code = 200, produces = "application/json")
public ModelMap getDemo2(@ApiParam(name = "userName", value = "编号", required = true) @PathVariable("userName") String userName) {
ModelMap map = new ModelMap();
map.addAttribute("userName", userName);
return map;
}
重启web服务访问:
Swagger ui 已经通过jar包导进来了所以直接访问
http://localhost:8080/SunnyApp/swagger-ui.html
即可
或者把Swagger ui 静态文件 放到自己喜欢的目录
在GitHub上下载SwaggerUI项目(https://github.com/swagger-api/swagger-ui),将dist下所有内容拷贝到本地项目/apidoc下面,结果目录如下图所示:
打开目录下的index.html文件,找到代码片段url = “http://petstore.swagger.io/v2/swagger.json“;修改为“/apidoc/v2/api-docs”。