重新认识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,还有RAMLjsonapi,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:
如果您觉得我的文章对您有帮助,请关注我的微信公众号,谢谢!
程序员打怪之路

posted @ 2020-03-27 15:29  从此寂静无声  阅读(...)  评论(...编辑  收藏