重新認識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:
如果您覺得我的文章對您有幫助，請關注我的微信公眾號，謝謝!