之前我在SpringBoot老鳥系列中專門花了大量的篇幅詳細(xì)介紹如何集成Swagger，以及如何對Swagger進(jìn)行擴(kuò)展讓其支持接口參數(shù)分組功能。詳情可見：SpringBoot 如何生成接口文檔，老鳥們都這么玩的！

可是當(dāng)我接觸到另一個(gè)接口文檔工具 smart-doc后，我覺得它比Swagger更適合集成在項(xiàng)目中，更適合老鳥們。今天我們就來介紹一下smart-doc組件的使用，作為對老鳥系列文章的一個(gè)補(bǔ)充。

swagger vs smart-doc

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

Swagger的代碼侵入性比較強(qiáng)

這個(gè)很容易理解，要讓Swagger生成接口文檔必須要給方法或字段添加對應(yīng)的注解，是存在代碼侵入的。

原生swagger不支持接口的參數(shù)分組

對于有做參數(shù)分組的接口，原生的Swagger并未支持，雖然我們通過擴(kuò)展其組件可以讓其支持參數(shù)分組，但是畢竟要開發(fā)，而且還未支持最新的Swagger3版本。

那作為對比，smart-doc 是基于接口源碼分析來生成接口文檔，完全做到零注解侵入，你只需要按照java標(biāo)準(zhǔn)注釋的寫，smart-doc就能幫你生成一個(gè)簡易明了的markdown 或是一個(gè)像GitBook樣式的靜態(tài)html文檔。官方地址：https://gitee.com/smart-doc-team/smart-doc

簡單羅列一下smart-doc的優(yōu)點(diǎn)：

• 零注解、零學(xué)習(xí)成本、只需要寫標(biāo)準(zhǔn)java注釋即可生成文檔。
• 基于源代碼接口定義自動(dòng)推導(dǎo)，強(qiáng)大的返回結(jié)構(gòu)推導(dǎo)。
• 支持Spring MVC,Spring Boot,Spring Boot Web Flux(controller書寫方式)。
• 支持Callable,Future,CompletableFuture等異步接口返回的推導(dǎo)。
• 支持JavaBean上的JSR303參數(shù)校驗(yàn)規(guī)范，支持參數(shù)分組。
• 對一些常用字段定義能夠生成有效的模擬值。
• …

接下來我們來看看SpringBoot中如何集成smart-doc。

SpringBoot集成 smart-doc

smart-doc支持多種方式生成接口文檔：maven插件、gradle插件、單元測試（不推薦），這里我才用的是基于maven插件生成，步驟如下：

引入依賴，版本選擇最新版本

<!--引入smart-doc--> <plugin><groupId>com.github.shalousun</groupId><artifactId>smart-doc-maven-plugin</artifactId><version>2.2.7</version><configuration><configFile>./src/main/resources/smart-doc.json</configFile><projectName>Smart-Doc初體驗(yàn)</projectName></configuration> </plugin>

重點(diǎn)在 configFile中指定smart-doc配置文件 smart-doc.json

新建配置文件smart-doc.json

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

指定smart-doc生成的文檔路徑，其他配置項(xiàng)可以參考官方wiki。

通過執(zhí)行maven 命令生成對應(yīng)的接口文檔

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

當(dāng)然也可以通過idea中的maven插件生成

4. 訪問接口文檔

生成接口文檔后我們通過 http://localhost:8080/doc/api.html查看，效果如下：

看到這里的同學(xué)可能會(huì)呵呵一笑，就這？啥也沒有呀！這還想讓我替換Swagger？

別急，剛剛只是體驗(yàn)了smart-doc的基礎(chǔ)功能，接下來我們通過豐富smart-doc的配置文件內(nèi)容來增強(qiáng)其功能。

功能增強(qiáng)

1. 開啟調(diào)試

一個(gè)優(yōu)秀的接口文檔工具調(diào)試功能必不能少，smart-doc支持在線調(diào)試功能，只需要加入如下幾個(gè)配置項(xiàng)：

{"serverUrl": "http://localhost:8080", -- 服務(wù)器地址"allInOne": true, -- 是否將文檔合并到一個(gè)文件中，一般推薦為true"outPath": "src/main/resources/static/doc", -- 指定文檔的輸出路徑"createDebugPage": true, -- 開啟測試"allInOneDocFileName":"index.html", -- 自定義文檔名稱"projectName": "初識(shí)smart-doc" -- 項(xiàng)目名稱 }

通過"createDebugPage": true 開啟debug功能，在讓生成smart-doc生成文檔時(shí)直接放入到 static/doc/下，這樣可以直接啟動(dòng)程序訪問頁面 http://localhost:8080/doc/index.html進(jìn)行開發(fā)調(diào)試。

有的開發(fā)人員直接在idea中使用【Open In Browser】打開smart-doc生成的debug頁面，如果非要這做，前端js請求后臺(tái)接口時(shí)就出現(xiàn)了跨域。因此你需要在后端配置跨域。

這里以 SpringBoot2.3.x 為例配置后端跨域：

@Configuration public class WebMvcAutoConfig implements WebMvcConfigurer {@Beanpublic CorsFilter corsFilter() {final UrlBasedCorsConfigurationSource urlBasedCorsConfigurationSource = new UrlBasedCorsConfigurationSource();final CorsConfiguration corsConfiguration = new CorsConfiguration();/* 是否允許請求帶有驗(yàn)證信息 */corsConfiguration.setAllowCredentials(true);/* 允許訪問的客戶端域名 */corsConfiguration.addAllowedOrigin("*");/* 允許服務(wù)端訪問的客戶端請求頭 */corsConfiguration.addAllowedHeader("*");/* 允許訪問的方法名,GET POST等 */corsConfiguration.addAllowedMethod("*");urlBasedCorsConfigurationSource.registerCorsConfiguration("/**", corsConfiguration);return new CorsFilter(urlBasedCorsConfigurationSource);} }

開啟跨域后我們就可以直接在靜態(tài)接口頁面中進(jìn)行調(diào)試了。

2. 通用響應(yīng)體

在 “SpringBoot 如何統(tǒng)一后端返回格式？老鳥們都是這樣玩的！”一文中我們通過實(shí)現(xiàn) ResponseBodyAdvice對所有返回值進(jìn)行了包裝，給前端返回統(tǒng)一的數(shù)據(jù)結(jié)構(gòu)ResultData，我們需要讓其在接口文檔中也有此功能，在配置文件追加配置內(nèi)容：

{"responseBodyAdvice":{ -- 通用響應(yīng)體"className":"com.jianzh5.blog.base.ResultData"} }

3. 自定義Header

在前后端分離項(xiàng)目中我們一般需要在請求接口時(shí)設(shè)置一個(gè)請求頭，如token，Authorization等…后端根據(jù)請求頭判斷是否為系統(tǒng)合法用戶，目前smart-doc也對其提供了支持。

在smart-doc配置文件 smart-doc.json中繼續(xù)追加如下配置內(nèi)容：

"requestHeaders": [ //設(shè)置請求頭，沒有需求可以不設(shè)置{"name": "token",//請求頭名稱"type": "string",//請求頭類型"desc": "自定義請求頭 - token",//請求頭描述信息"value":"123456",//不設(shè)置默認(rèn)null"required": false,//是否必須"since": "-",//什么版本添加的改請求頭"pathPatterns": "/smart/say",//只有以/smart/say 開頭的url才會(huì)有此請求頭"excludePathPatterns":"/smart/add,/smart/edit" // url=/app/page/將不會(huì)有該請求頭} ]

效果如下：

4. 參數(shù)分組

演示一下smart-doc對于參數(shù)分組的支持

新增操作時(shí)，age、level為必填項(xiàng)，sex為非必填。

編輯操作時(shí)，id，appid，leven為必填項(xiàng)，sex為非必填。

通過上面的效果可以看出smart-doc對于參數(shù)分組是完全支持的。

5. idea配置doc

自定義的tag默認(rèn)是不會(huì)自動(dòng)提示的，需要用戶在idea中進(jìn)行設(shè)置。設(shè)置好后即可使用，下面以設(shè)置smart-doc自定義的mock tag為例，設(shè)置操作如下：

### 6. 完整配置

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

{"serverUrl": "http://localhost:8080","allInOne": true,"outPath": "src/main/resources/static/doc","createDebugPage": true,"allInOneDocFileName":"index.html","projectName": "初識(shí)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"}] }

小結(jié)

其實(shí)沒什么可總結(jié)的，smart-doc使用非常簡單，官方文檔也非常詳細(xì)，只要你會(huì)寫標(biāo)準(zhǔn)的java注釋就可以給你生成詳細(xì)的接口文檔。（如果你說你不會(huì)寫注釋，那這篇文章可能不太適合你） 而且在引入smart-doc后還可以強(qiáng)制要求開發(fā)人員給接口編寫注釋，保證團(tuán)隊(duì)代碼風(fēng)格不會(huì)出現(xiàn)很大差異。

老鳥系列源碼已經(jīng)上傳至GitHub，需要的點(diǎn)擊下方卡片關(guān)注并回復(fù)關(guān)鍵字 0923 獲取

總結(jié)

以上是生活随笔為你收集整理的SpringBoot 集成接口文档，老鸟们也被打脸了！的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。