swagger是什么（十三）

前言：

swagger：神氣十足，大搖大擺

在用Springboot進行開發時，有的實體類上用到了注解@ApiModelProperty("接受人代碼")，特此整理此注解的出處及作用。

說白了，swagger就是為了方便系統生成API文檔。而ApiModel與ApiModelProperty都是swagger的注解。

一、swagger是什么

1、是一款讓你更好的書寫API文檔的規范且完整框架。
2、提供描述、生產、消費和可視化RESTful Web Service。
3、是由龐大工具集合支撐的形式化規范。這個集合涵蓋了從終端用戶接口、底層代碼庫到商業API管理的方方面面。

參看swagger學習鏈接：https://www.e-learn.cn/content/qita/1542698

二、Swagger有什么用

swagger是一個流行的API開發框架，這個框架以“開放API聲明”（OpenAPI Specification，OAS）為基礎，對整個API的開發周期都提供了相應的解決方案，是一個非常龐大的項目（包括設計、文檔以及測試和部署，幾乎支持所有語言）。
Swagger 是一個規范和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。總體目標是使客戶端和文件系統作為服務器以同樣的速度來更新。文件的方法，參數和模型緊密集成到服務器端的代碼，允許API來始終保持同步。Swagger 讓部署管理和使用功能強大的API從未如此簡單。

三、SpringBoot 與 Swagger2

由於java的強大的注解功能,我們使用SpringBoot來結合Swagger2,在使用起來非常簡單.
由於Spring的流行，Marty Pitt編寫了一個基於Spring的組件swagger-springmvc，用於將swagger集成到springmvc中來。
Springfox的前身是swagger-springmvc，是一個開源的API doc框架，可以將我們的Controller的方法以文檔的形式展現。
springfox大致原理:
springfox的大致原理就是，在項目啟動的過程中，spring上下文在初始化的過程，框架自動根據配置加載一些swagger相關的bean到當前的上下文中，並自動掃描系統中可能需要生成api文檔那些類，並生成相應的信息緩存起來。如果項目MVC控制層用的是springMvc那么會自動掃描所有Controller類，並生成對應的文檔描述數據。該數據是json格式，通過路徑：項目地址/ v2/api-docs可以訪問到該數據，然后swaggerUI根據這份數據生成相應的文檔描述界面。因為我們能拿到這份數據，所以我們也可以生成自己的頁面.

參看鏈接：

https://blog.csdn.net/jamieblue1/article/details/99847744

https://blog.csdn.net/weixin_37509652/article/details/80094370

四、重新認識Swagger與springfox

做過Java后端開發的同學應該都用使用過Springfox和Swagger，但我相信很多同學都對這兩個工具的理解和使用都有問題。

4.1 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：壓力測試和性能測試的自動化工具

4.2 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

4.3 Swagger注解的濫用

在代碼中的注解已經存儲了大量的信息，如果再用swagger-core的注解將這些信息用另一種方式表達出來，很容易造成改了這里忘了改那里，即修改不同步。因此Springfox的開發者不推薦大家使用swagger-core的注解來描述API，認為swagger-core的注解只是補充，只能用於實現其他方法都不能實現的調整或者覆蓋。例如，更應該使用Jackson的注解，而不是@ApiModelProperty；更應該使用@NotNull或者@RequestParam#required，而不是在文檔里寫一句此字段必填。

但是，springfox的開發者忽略了一個事實，中文開發者用swagger-core的注解更多的是用來添加中文描述，所以，該用的時候還是用吧。

參看鏈接：https://www.cnblogs.com/jason1990/p/12581773.html

五、@ApiModel和@ApiModelProperty用法

5.1@ApiModel

使用場景：在實體類上邊使用，標記類是swagger的解析類。
概述：提供有關swagger模型的其它信息，類將在操作中用作類型時自動內省。
用法：

5.2 @ApiModelProperty

使用場景：使用在被 @ApiModel 注解的模型類的屬性上。表示對model屬性的說明或者數據操作更改 。
概述：添加和操作模型屬性的數據。
用法：

@ApiModel(value="user對象",description="用戶對象user")
public class User implements Serializable{
    private static final long serialVersionUID = 1L;
     @ApiModelProperty(value="用戶名",name="username",example="xingguo")
     private String username;
     @ApiModelProperty(value="狀態",name="state",required=true)
      private Integer state;
      private String password;
      private String nickName;
      private Integer isDeleted;

      @ApiModelProperty(value="id數組",hidden=true)
      private String[] ids;
      private List<String> idList;
     //省略get/set
}

參看鏈接：

https://blog.csdn.net/weixin_39189376/article/details/97926012

https://www.cnblogs.com/huanghuanghui/p/9086860.html