重新认识Swagger和Springfox

做过Java后端开发的同学应该都用使用过Springfox和Swagger，但我相信很多同学都对这两个工具的理解和使用都有问题。

Swagger是什么

根据官网的介绍，Swagger是一系列用于Restful API开发的工具，开源的部分包括：

• OpenAPI Specification：API规范，规定了如何描述一个系统的API
• Swagger Codegen：用于通过API规范生成服务端和客户端代码
• Swagger Editor：用来编写API规范
• Swagger UI：用于展示API规范

非开源的部分包括：

• Swagger Hub：云服务，相当于Editor + Codegen + UI
• Swagger Inspector：手动测试API的工具
• SoapUI Pro：功能测试和安全测试的自动化工具
• LoadUI Pro：压力测试和性能测试的自动化工具

Springfox是什么

在大量的中文教程中，Springfox以这样的方式出现

<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>

第二个看起来应该是springfox封装/修改的Swagger UI，第一个应该就是Springfox本体了，但为什么artifact有个swagger2的后缀？

这就要从Springfox是什么说起了。Springfox其实是一个通过扫描代码提取代码中的信息，生成API文档的工具。API文档的格式不止Swagger的OpenAPI Specification，还有RAML，jsonapi，Springfox的目标同样包括支持这些格式。这就能解释那个swagger2的后缀了，这只是Springfox对Swagger的支持。

在Swagger的教程中，都会提到@Api、@ApiModel、@ApiOperation这些注解，这些注解其实不是Springfox的，而是Swagger的。springfox-swagger2这个包依赖了swagger-core这个包，而这些注解正是在这里面。但是，swagger-core这个包是只支持JAX-RS2的，并不支持常用的Spring MVC。这就是springfox-swagger的作用了，它将上面那些用于JAX-RS2的注解适配到了Spring MVC上。

除了Spring MVC外，Springfox还支持如下库

• Spring Data REST
• JSR 303，这项标准的参考实现是Hibernate Validator

Swagger注解的滥用

在代码中的注解已经存储了大量的信息，如果再用swagger-core的注解将这些信息用另一种方式表达出来，很容易造成改了这里忘了改那里，即修改不同步。因此Springfox的开发者不推荐大家使用swagger-core的注解来描述API，认为swagger-core的注解只是补充，只能用于实现其他方法都不能实现的调整或者覆盖。例如，更应该使用Jackson的注解，而不是@ApiModelProperty；更应该使用@NotNull或者@RequestParam#required，而不是在文档里写一句此字段必填。

但是，springfox的开发者忽略了一个事实，中文开发者用swagger-core的注解更多的是用来添加中文描述，所以，该用的时候还是用吧。

PS:
如果您觉得我的文章对您有帮助，请关注我的微信公众号，谢谢!