Swagger介紹及使用

作者：wuqke
連結：https://www.jianshu.com/p/349e130e40d5
來源：簡書
著作權歸作者所有。商業轉載請聯絡作者獲得授權，非商業轉載請註明出處。

 

一、導語

相信無論是前端還是後端開發，都或多或少地被介面文件折磨過。前端經常抱怨後端給的介面文件與實際情況不一致。後端又覺得編寫及維護介面文件會耗費不少精力，經常來不及更新。其實無論是前端呼叫後端，還是後端呼叫後端，都期望有一個好的介面文件。但是這個介面文件對於程式設計師來說，就跟註釋一樣，經常會抱怨別人寫的程式碼沒有寫註釋，然而自己寫起程式碼起來，最討厭的，也是寫註釋。所以僅僅只通過強制來規範大家是不夠的，隨著時間推移，版本迭代，介面文件往往很容易就跟不上程式碼了。

 

二、Swagger是什麼？它能幹什麼？

 

發現了痛點就要去找解決方案。解決方案用的人多了，就成了標準的規範，這就是Swagger的由來。通過這套規範，你只需要按照它的規範去定義介面及介面相關的資訊。再通過Swagger衍生出來的一系列專案和工具，就可以做到生成各種格式的介面文件，生成多種語言的客戶端和服務端的程式碼，以及線上介面除錯頁面等等。這樣，如果按照新的開發模式，在開發新版本或者迭代版本的時候，只需要更新Swagger描述檔案，就可以自動生成介面文件和客戶端服務端程式碼，做到呼叫端程式碼、服務端程式碼以及介面文件的一致性。

但即便如此，對於許多開發來說，編寫這個yml或json格式的描述檔案，本身也是有一定負擔的工作，特別是在後面持續迭代開發的時候，往往會忽略更新這個描述檔案，直接更改程式碼。久而久之，這個描述檔案也和實際專案漸行漸遠，基於該描述檔案生成的介面文件也失去了參考意義。所以作為Java屆服務端的大一統框架Spring，迅速將Swagger規範納入自身的標準，建立了Spring-swagger專案，後面改成了現在的Springfox。通過在專案中引入Springfox，可以掃描相關的程式碼，生成該描述檔案，進而生成與程式碼一致的介面文件和客戶端程式碼。這種通過程式碼生成介面文件的形式，在後面需求持續迭代的專案中，顯得尤為重要和高效。

三、框架說明及使用

1、說明

現在SWAGGER官網主要提供了幾種開源工具，提供相應的功能。可以通過配置甚至是修改原始碼以達到你想要的效果。

• 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.2、專案迭代階段
到這個階段，事情就簡單很多了。後續後臺人員，無需關注Swagger描述檔案和介面文件，有需求變更導致介面變化，直接寫程式碼就好了。把呼叫層的程式碼做個修改，然後生成新的描述檔案和介面文件後，給到前端即可。真正做到了一勞永逸。

2.3、流程
總結一下就是通過下面這兩種流程中的一種，可以做到程式碼和介面文件的一致性，服務端開發再也不用花費精力去維護介面文件。

流程一

流程二：

四、給Mock系統的正常請求及響應全流程資料

很多時候，如果你能在提供介面文件的同時，把所有介面的模擬請求響應資料也提供給前端。或者有Mock系統，直接將這些模擬資料錄入到Mock系統中，那將會提高前端的開發效率，減少許多發生在聯調時候才會發生的問題。

通過適當地在程式碼中加入swagger的註解，可以讓你的介面文件描述資訊更加詳細，如果你把每個出入引數的示例值都配上，那前端就可以直接在介面文件中拿到模擬資料。相關的註解類及引數配置可以參考文末他人寫的技術文章，這裡也不作展開了。

相關示例註解程式碼和效果圖如下：

#####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 FFResponseModel<T> implements Serializable {

    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;
    
}


    

五、效果圖

模擬請求資料包文：

模擬返回資料包文：

六、總結

其實歸根到底，使用Swagger，就是把相關的資訊儲存在它定義的描述檔案裡面（yml或json格式），再通過維護這個描述檔案可以去更新介面文件，以及生成各端程式碼。而Springfox-swagger,則可以通過掃描程式碼去生成這個描述檔案，連描述檔案都不需要再去維護了。所有的資訊，都在程式碼裡面了。程式碼即介面文件，介面文件即程式碼。

七、相關技術資料站

• SWAGGER 官網：https://swagger.io/
• API表達工具：Swagger：https://blog.csdn.net/zmh458/article/details/78766895
• Swagger 常用註解使用詳解：https://blog.csdn.net/wyb880501/article/details/79576784