SpringBoot 生成介面文件,我用smart-doc,一款比Swagger更nice的工具!

語言: CN / TW / HK

之前我在SpringBoot老鳥系列中專門花了大量的篇幅詳細介紹如何整合Swagger,以及如何對Swagger進行擴充套件讓其支援介面引數分組功能。詳情可見:SpringBoot 如何生成介面文件,老鳥們都這麼玩的!

可是當我接觸到另一個介面文件工具 smart-doc後,我覺得它比Swagger更適合整合在專案中,更適合老鳥們。今天我們就來介紹一下smart-doc元件的使用,作為對老鳥系列文章的一個補充。

swagger vs smart-doc

首先我們先看一下Swagger元件目前存在的主要問題:

  1. Swagger的程式碼侵入性比較強

這個很容易理解,要讓Swagger生成介面文件必須要給方法或欄位新增對應的註解,是存在程式碼侵入的。 2. 原生swagger不支援介面的引數分組

對於有做引數分組的介面,原生的Swagger並未支援,雖然我們通過擴充套件其元件可以讓其支援引數分組,但是畢竟要開發,而且還未支援最新的Swagger3版本。

那作為對比,smart-doc 是基於介面原始碼分析來生成介面文件,完全做到零註解侵入,你只需要按照java標準註釋的寫,smart-doc就能幫你生成一個簡易明瞭的markdown 或是一個像GitBook樣式的靜態html文件。官方地址:https://gitee.com/smart-doc-team/smart-doc

簡單羅列一下smart-doc的優點:

  • 零註解、零學習成本、只需要寫標準java註釋即可生成文件。
  • 基於原始碼介面定義自動推導,強大的返回結構推導。
  • 支援Spring MVC,Spring Boot,Spring Boot Web Flux(controller書寫方式)。
  • 支援Callable,Future,CompletableFuture等非同步介面返回的推導。
  • 支援JavaBean上的JSR303引數校驗規範,支援引數分組。
  • 對一些常用欄位定義能夠生成有效的模擬值。
  • ...

smartdoc.gif

接下來我們來看看SpringBoot中如何整合smart-doc。

SpringBoot整合 smart-doc

smart-doc支援多種方式生成介面文件:maven外掛、gradle外掛、單元測試(不推薦),這裡我才用的是基於maven外掛生成,步驟如下:

  1. 引入依賴,版本選擇最新版本

```

com.github.shalousun smart-doc-maven-plugin 2.2.7 ./src/main/resources/smart-doc.json Smart-Doc初體驗 ```

重點在 configFile中指定smart-doc配置檔案 smart-doc.json

  1. 新建配置檔案smart-doc.json

{ "outPath": "src/main/resources/static/doc" }

指定smart-doc生成的文件路徑,其他配置項可以參考官方wiki。

  1. 通過執行maven 命令生成對應的介面文件

//生成html mvn -Dfile.encoding=UTF-8 smart-doc:html

當然也可以通過idea中的maven外掛生成

圖片 4. 訪問介面文件

生成介面文件後我們通過 http://localhost:8080/doc/api.html檢視,效果如下:

圖片 看到這裡的同學可能會呵呵一笑,就這?啥也沒有呀!這還想讓我替換Swagger?

圖片別急,剛剛只是體驗了smart-doc的基礎功能,接下來我們通過豐富smart-doc的配置檔案內容來增強其功能。

功能增強

1. 開啟除錯

一個優秀的介面文件工具除錯功能必不能少,smart-doc支援線上除錯功能,只需要加入如下幾個配置項:

{ "serverUrl": "http://localhost:8080", -- 伺服器地址 "allInOne": true, -- 是否將文件合併到一個檔案中,一般推薦為true "outPath": "src/main/resources/static/doc", -- 指定文件的輸出路徑 "createDebugPage": true, -- 開啟測試 "allInOneDocFileName":"index.html", -- 自定義文件名稱 "projectName": "初識smart-doc" -- 專案名稱 }

通過"createDebugPage": true 開啟debug功能,在讓生成smart-doc生成文件時直接放入到 static/doc/下,這樣可以直接啟動程式訪問頁面 http://localhost:8080/doc/index.html進行開發除錯。

圖片

有的開發人員直接在idea中使用【Open In Browser】開啟smart-doc生成的debug頁面,如果非要這做,前端js請求後臺介面時就出現了跨域。因此你需要在後端配置跨域。

這裡以 SpringBoot2.3.x 為例配置後端跨域:

``` @Configuration public class WebMvcAutoConfig implements WebMvcConfigurer {

@Bean
public CorsFilter corsFilter() {
    final UrlBasedCorsConfigurationSource urlBasedCorsConfigurationSource = new UrlBasedCorsConfigurationSource();
    final CorsConfiguration corsConfiguration = new CorsConfiguration();
    /* 是否允許請求帶有驗證資訊 */
    corsConfiguration.setAllowCredentials(true);
    /* 允許訪問的客戶端域名 */
    corsConfiguration.addAllowedOrigin("*");
    /* 允許服務端訪問的客戶端請求頭 */
    corsConfiguration.addAllowedHeader("*");
    /* 允許訪問的方法名,GET POST等 */
    corsConfiguration.addAllowedMethod("*");
    urlBasedCorsConfigurationSource.registerCorsConfiguration("/**", corsConfiguration);
    return new CorsFilter(urlBasedCorsConfigurationSource);
}

} ```

開啟跨域後我們就可以直接在靜態介面頁面中進行除錯了。

2. 通用響應體

在 “SpringBoot 如何統一後端返回格式?老鳥們都是這樣玩的!”一文中我們通過實現 ResponseBodyAdvice對所有返回值進行了包裝,給前端返回統一的資料結構ResultData,我們需要讓其在介面文件中也有此功能,在配置檔案追加配置內容:

{ "responseBodyAdvice":{ -- 通用響應體 "className":"com.jianzh5.blog.base.ResultData" } }

圖片

3. 自定義Header

在前後端分離專案中我們一般需要在請求介面時設定一個請求頭,如token,Authorization等...後端根據請求頭判斷是否為系統合法使用者,目前smart-doc也對其提供了支援。

在smart-doc配置檔案 smart-doc.json中繼續追加如下配置內容:

"requestHeaders": [ //設定請求頭,沒有需求可以不設定 { "name": "token",//請求頭名稱 "type": "string",//請求頭型別 "desc": "自定義請求頭 - token",//請求頭描述資訊 "value":"123456",//不設定預設null "required": false,//是否必須 "since": "-",//什麼版本新增的改請求頭 "pathPatterns": "/smart/say",//只有以/smart/say 開頭的url才會有此請求頭 "excludePathPatterns":"/smart/add,/smart/edit" // url=/app/page/將不會有該請求頭 } ]

效果如下:

圖片

4. 引數分組

演示一下smart-doc對於引數分組的支援

圖片 新增操作時,age、level為必填項,sex為非必填。

圖片 編輯操作時,id,appid,leven為必填項,sex為非必填。

通過上面的效果可以看出smart-doc對於引數分組是完全支援的。

5. idea配置doc

自定義的tag預設是不會自動提示的,需要使用者在idea中進行設定。設定好後即可使用,下面以設定smart-doc自定義的mock tag為例,設定操作如下:

圖片### 6. 完整配置

附上完整配置,如果還需要其他配置大家可以參考wiki自行引入。

{ "serverUrl": "http://localhost:8080", "allInOne": true, "outPath": "src/main/resources/static/doc", "createDebugPage": true, "allInOneDocFileName":"index.html", "projectName": "初識smart-doc", "packageFilters": "com.jianzh5.blog.smartdoc.*", "errorCodeDictionaries": [{ "title": "title", "enumClassName": "com.jianzh5.blog.base.ReturnCode", "codeField": "code", "descField": "message" }], "responseBodyAdvice":{ "className":"com.jianzh5.blog.base.ResultData" }, "requestHeaders": [{ "name": "token", "type": "string", "desc": "自定義請求頭 - token", "value":"123456", "required": false, "since": "-", "pathPatterns": "/smart/say", "excludePathPatterns":"/smart/add,/smart/edit" }] }

小結

其實沒什麼可總結的,smart-doc使用非常簡單,官方文件也非常詳細,只要你會寫標準的java註釋就可以給你生成詳細的介面文件。(如果你說你不會寫註釋,那這篇文章可能不太適合你) 而且在引入smart-doc後還可以強制要求開發人員給介面編寫註釋,保證團隊程式碼風格不會出現很大差異。

老鳥系列原始碼已經上傳至GitHub,需要的在公號【JAVA日知錄】回覆關鍵字 0923 獲取