Swagger使用总结（十九）

1. Swagger是什么？

Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。

官方说法：Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。整体目标是使客户端和文件系统做为服务器以一样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，容许API来始终保持同步。

我的以为，swagger的一个最大的优势是能实时同步api与文档。在项目开发过程当中，发生过屡次：修改代码可是没有更新文档，前端仍是按照老旧的文档进行开发，在联调过程当中才发现问题的状况（固然依据开闭原则，对接口的修改是不容许的，可是在项目不稳定阶段，这种状况很难避免）。

2. spring boot 集成 Swagger

目前维护的系统是基于springboot框架开发的，所以本文会详细描述springboot与swagger集成的过程。

spring-boot系统集成swagger须要进行以下操做：

1. 添加maven依赖，须要在系统的pom中添加以下依赖：

    <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.2.2</version> </dependency> 

2. 添加swagger配置文件，配置文件以下：

   @Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .select() // 选择那些路径和api会生成document .apis(RequestHandlerSelectors.any()) // 对全部api进行监控 .paths(PathSelectors.any()) // 对全部路径进行监控 .build(); } }

   经过注解EnableSwagger2声明Swagger的可用性，此处会定义一个类型为Docket的bean，
   关于docket类的说明以下：

   A builder which is intended to be the primary interface into the swagger-springmvc framework.Provides sensible defaults and convenience methods for configuration.

   Docket的select()方法会提供给swagger-springmvc framework的一个默认构造器（ApiSelectorBuilder），这个构造器为配置swagger提供了一系列的默认属性和便利方法。

3. 测试

   经过访问：http://localhost:8080/your-app-root/v2/api-docs ，能测试生成的api是否可用。此时返回的是一个json形式的页面，可读性很差。能够经过Swagger UI来生成一个可读性良好的api页面。具体作法就是，在pom中添加相关依赖。以下：

   <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.2.2</version> </dependency>

   再次访问：http://localhost:8080/your-app-root/swagger-ui.html 就能够看到可读性较好的api文档页面。

4. 注意：

   1. http://localhost:8080/your-app-root/v2/api-docs 中your-app-root指的你的wabapp的根路径，我目前的webapp就默认在根路径下，因此地址是：http://localhost:8080/v2/api-docs
   2. spring-mvc上引用swagger须要作其余相关的配置，具体请查看参考文献
   3. swagger对restful风格的api支持的比较好，非restful风格的api支持的不是很好，对于非restful风格的api或者其余语言（非java语言）能够采用 http://editor.swagger 编辑器来收工完成相关的API编写

       

参考文献

1. swagger-2-documentation-for-spring-rest-api