Swagger介紹及使用
導語：
相信無論是前端還是後端開發，都或多或少地被接口文檔折磨過。前端經常抱怨後端給的接口文檔與實際情況不一致。後端又覺得編寫及維護接口文檔會耗費不少精力，經常來不及更新。其實無論是前端調用後端，還是後端調用後端，都期望有一個好的接口文檔。但是這個接口文檔對於程序員來說，就跟註釋一樣，經常會抱怨別人寫的代碼沒有寫註釋，然而自己寫起代碼起來，最討厭的，也是寫註釋。所以僅僅只通過強制來規範大家是不夠的，隨著時間推移，版本迭代，接口文檔往往很容易就跟不上代碼了。
Swagger是什麼？它能幹什麼？
image1200×460 65.8 KB
發現了痛點就要去找解決方案。解決方案用的人多了，就成了標準的規範，這就是Swagger的由來。通過這套規範，你只需要按照它的規範去定義接口及接口相關的信息。再通過Swagger衍生出來的一系列項目和工具，就可以做到生成各種格式的接口文檔，生成多種語言的客戶端和服務端的代碼，以及在線接口調試頁面等等。這樣，如果按照新的開發模式，在開發新版本或者迭代版本的時候，只需要更新Swagger描述文件，就可以自動生成接口文檔和客戶端服務端代碼，做到調用端代碼、服務端代碼以及接口文檔的一致性。
但即便如此，對於許多開發來說，編寫這個yml或json格式的描述文件，本身也是有一定負擔的工作，特別是在後面持續迭代開發的時候，往往會忽略更新這個描述文件，直接更改代碼。久而久之，這個描述文件也和實際項目漸行漸遠，基於該描述文件生成的接口文檔也失去了參考意義。所以作為Java屆服務端的大一統框架Spring，迅速將Swagger規範納入自身的標準，建立了Spring-swagger項目，後面改成了現在的Springfox。通過在項目中引入Springfox，可以掃描相關的代碼，生成該描述文件，進而生成與代碼一致的接口文檔和客戶端代碼。這種通過代碼生成接口文檔的形式，在後面需求持續迭代的項目中，顯得尤為重要和高效。
框架說明及使用
1.說明
現在SWAGGER官網主要提供了幾種開源工具，提供相應的功能。可以通過配置甚至是修改源碼以達到你想要的效果。
image1016×690 115 KB
Swagger Codegen : 通過Codegen 可以將描述文件生成html格式和cwiki形式的接口文檔，同時也能生成多種語言的服務端和客戶端的代碼。支持通過jar包，docker，node等方式在本地化執行生成。也可以在後面的Swagger Editor中在線生成。
Swagger UI :提供了一個可視化的UI頁面展示描述文件。接口的調用方、測試、項目經理等都可以在該頁面中對相關接口進行查閱和做一些簡單的接口請求。該項目支持在線導入描述文件和本地部署UI項目。
Swagger Editor : 類似於markendown編輯器的編輯Swagger描述文件的編輯器，該編輯支持實時預覽描述文件的更新效果。也提供了在線編輯器和本地部署編輯器兩種方式。
Swagger Inspector : 感覺和postman差不多，是一個可以對接口進行測試的在線版的postman。比在Swagger UI裡面做接口請求，會返回更多的信息，也會保存你請求的實際請求參數等數據。
Swagger Hub ：集成了上面所有項目的各個功能，你可以以項目和版本為單位，將你的描述文件上傳到Swagger Hub中。在Swagger Hub中可以完成上面項目的所有工作，需要註冊賬號，分免費版和收費版。
PS：
Springfox Swagger : Spring 基於swagger規範，可以將基於SpringMVC和Spring Boot項目的項目代碼，自動生成JSON格式的描述文件。本身不是屬於Swagger官網提供的，在這裡列出來做個說明，方便後面作一個使用的展開。
2.基於Spring框架的Swagger流程應用
這裡不會介紹Swagger的工具具體如何使用，不會講yml或者json格式描述文件的語法規範，也不會講如何在SpringMVC或者Spring Boot中配置Springfox－swagger。這些都能從網上找到，而且配置起來都非常的簡單。
這裡想講的是如何結合現有的工具和功能，設計一個流程，去保證一個項目從開始開發到後面持續迭代的時候，以最小代價去維護代碼、接口文檔以及Swagger描述文件。
2.1 項目開始階段
一般來說，接口文檔都是由服務端來編寫的。在項目開發階段的時候，服務端開發可以視情況來決定是直接編寫服務端調用層代碼，還是寫Swagger描述文件。建議是如果項目啟動階段，就已經搭好了後臺框架，那可以直接編寫服務端被調用層的代碼（即controller及其入參出參對象），然後通過Springfox－swagger 生成swagger json描述文件。如果項目啟動階段並沒有相關後臺框架，而前端對接口文檔追得緊，那就建議先編寫swagger描述文件，通過該描述文件生成接口文檔。後續後臺框架搭好了，也可以生成相關的服務端代碼。
2.1 項目迭代階段
到這個階段，事情就簡單很多了。後續後臺人員，無需關注Swagger描述文件和接口文檔，有需求變更導致接口變化，直接寫代碼就好了。把調用層的代碼做個修改，然後生成新的描述文件和接口文檔後，給到前端即可。真正做到了一勞永逸。
2.3流程
總結一下就是通過下面這兩種流程中的一種，可以做到代碼和接口文檔的一致性，服務端開發再也不用花費精力去維護接口文檔。
流程一
image1200×536 35.8 KB
image.png
流程二
image1200×457 32.8 KB
image.png
給Mock系統的正常請求及響應全流程數據
很多時候，如果你能在提供接口文檔的同時，把所有接口的模擬請求響應數據也提供給前端。或者有Mock系統，直接將這些模擬數據錄入到Mock系統中，那將會提高前端的開發效率，減少許多發生在聯調時候才會發生的問題。
通過適當地在代碼中加入swagger的註解，可以讓你的接口文檔描述信息更加詳細，如果你把每個出入參數的示例值都配上，那前端就可以直接在接口文檔中拿到模擬數據。相關的註解類及參數配置可以參考文末他人寫的技術文章，這裡也不作展開了。
相關示例註解代碼和效果圖如下：
<code>#####Controller代碼
@Override
@ApiOperation(value = "post請求調用示例", notes = "invokePost說明", httpMethod = "POST")
public FFResponseModel<demooutputdto> invokePost(@ApiParam(name="傳入對象",value="傳入json格式",required=true) @RequestBody @Valid DemoDto input) {
log.info("/testPost is called. input=" + input.toString());
return new FFResponseModel(Errcode.SUCCESS_CODE, Errcode.SUCCESS_MSG);
}
#####接口請求入參對象
@Data
@ApiModel(value="演示類",description="請求參數類" )
public class DemoDto implements Serializable {
private static final long serialVersionUID = 1L;
@NotNull
@ApiModelProperty(value = "defaultStr",example="mockStrValue")
private String strDemo;
@NotNull
@ApiModelProperty(example="1234343523",required = true)
private Long longNum;
@NotNull
@ApiModelProperty(example="111111.111")
private Double doubleNum;
@NotNull
@ApiModelProperty(example="2018-12-04T13:46:56.711Z")
private Date date;
}
#####接口請求出參公共類
@ApiModel(value="基礎返回類",description="基礎返回類")
public class FFResponseModelimplements Serializable { /<demooutputdto>/<code>
private static final long serialVersionUID = -2215304260629038881L;
// 狀態碼
@ApiModelProperty(example="成功")
private String code;
// 業務提示語
@ApiModelProperty(example="000000")
private String msg;
// 數據對象
private T data;
...
}
#####接口請求出參實際數據對象
@Data
public class DemoOutputDto {
private String res;
@NotNull
@ApiModelProperty(value = "defaultOutputStr",example="mockOutputStrValue")
private String outputStrDemo;
@NotNull
@ApiModelProperty(example="6666666",required = true)
private Long outputLongNum;
@NotNull
@ApiModelProperty(example="88888.888")
private Double outputDoubleNum;
@NotNull
@ApiModelProperty(example="2018-12-12T11:11:11.111Z")
private Date outputDate;
}
效果圖
image1200×909 142 KB
總結
其實歸根到底，使用Swagger，就是把相關的信息存儲在它定義的描述文件裡面（yml或json格式），再通過維護這個描述文件可以去更新接口文檔，以及生成各端代碼。而Springfox-swagger,則可以通過掃描代碼去生成這個描述文件，連描述文件都不需要再去維護了。所有的信息，都在代碼裡面了。代碼即接口文檔，接口文檔即代碼。
作者：wuqke
原文：https://www.jianshu.com/p/349e130e40d5
閱讀更多 泡泡糖就是糖 的文章
