做过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:
如果您觉得我的文章对您有帮助，请关注我的微信公众号，谢谢!
