還在用Swagger？試試這款零注解侵入的API文檔生成工具，跟Postman絕配！
源?/?? ? ? ??文/?
前后端接口聯(lián)調(diào)需要API文檔，我們經(jīng)常會(huì)使用工具來生成。之前經(jīng)常使用Swagger來生成，最近發(fā)現(xiàn)一款好用的API文檔生成工具
smart-doc, 它有著很多Swagger不具備的特點(diǎn)，推薦給大家。
聊聊Swagger
在我們使用Swagger的時(shí)候，經(jīng)常會(huì)需要用到它的注解，比如@Api、@ApiOperation這些，Swagger通過它們來生成API文檔。比如下面的代碼：
Swagger對(duì)代碼的入侵性比較強(qiáng)，有時(shí)候代碼注釋和注解中的內(nèi)容有點(diǎn)重復(fù)了。有沒有什么工具能實(shí)現(xiàn)零注解入侵，直接根據(jù)代碼注釋生成API文檔呢？smart-doc恰好是這種工具！
smart-doc簡(jiǎn)介
smart-doc是一款A(yù)PI文檔生成工具，無需多余操作，只要你規(guī)范地寫好代碼注釋，就能生成API文檔。同時(shí)能直接生成Postman調(diào)試文件，一鍵導(dǎo)入Postman即可調(diào)試，非常好用！
smart-doc具有如下優(yōu)點(diǎn)：
生成API文檔
接下來我們把
smart-doc集成到SpringBoot項(xiàng)目中，體驗(yàn)一下它的API文檔生成功能。
首先我們需要在項(xiàng)目中添加 smart-doc的Maven插件，可以發(fā)現(xiàn)smart-doc就是個(gè)插件，連依賴都不用添加，真正零入侵啊；
<plugin>
????<groupId>com.github.shalousungroupId>
????<artifactId>smart-doc-maven-pluginartifactId>
????<version>2.2.8version>
????<configuration>
????????
????????<configFile>./src/main/resources/smart-doc.jsonconfigFile>
????????
????????<projectName>mall-tiny-smart-docprojectName>
????configuration>
plugin>
接下來在項(xiàng)目的 resources目錄下，添加配置文件smart-doc.json，屬性說明直接參考注釋即可；
{
??"serverUrl":?"http://localhost:8088",?//指定后端服務(wù)訪問地址
??"outPath":?"src/main/resources/static/doc",?//指定文檔的輸出路徑，生成到項(xiàng)目靜態(tài)文件目錄下，隨項(xiàng)目啟動(dòng)可以查看
??"isStrict":?false,?//是否開啟嚴(yán)格模式
??"allInOne":?true,?//是否將文檔合并到一個(gè)文件中
??"createDebugPage":?false,?//是否創(chuàng)建可以測(cè)試的html頁面
??"packageFilters":?"com.macro.mall.tiny.controller.*",?//controller包過濾
??"style":"xt256",?//基于highlight.js的代碼高設(shè)置
??"projectName":?"mall-tiny-smart-doc",?//配置自己的項(xiàng)目名稱
??"showAuthor":false,?//是否顯示接口作者名稱
??"allInOneDocFileName":"index.html"?//自定義設(shè)置輸出文檔名稱
}
打開IDEA的Maven面板，雙擊 smart-doc插件的smart-doc:html按鈕，即可生成API文檔；
此時(shí)我們可以發(fā)現(xiàn)，在項(xiàng)目的 static/doc目錄下已經(jīng)生成如下文件；
運(yùn)行項(xiàng)目，訪問生成的API接口文檔，發(fā)現(xiàn)文檔非常詳細(xì)，包括了請(qǐng)求參數(shù)和響應(yīng)結(jié)果的各種說明，訪問地址：http://localhost:8088/doc/index.html
我們回過來看下實(shí)體類的代碼，可以發(fā)現(xiàn)我們只是規(guī)范地添加了字段注釋，生成文檔的時(shí)候就自動(dòng)有了；
public?class?PmsBrand?implements?Serializable?{
????/**
?????*?ID
?????*/
????private?Long?id;
????/**
?????*?名稱
?????*?@required
?????*/
????private?String?name;
????/**
?????*?首字母
?????*?@since?1.0
?????*/
????private?String?firstLetter;
????/**
?????*?排序
?????*/
????private?Integer?sort;
????/**
?????*?是否為品牌制造商(0,1)
?????*/
????private?Integer?factoryStatus;
????/**
?????*?顯示狀態(tài)(0,1)
?????*?@ignore
?????*/
????private?Integer?showStatus;
????/**
?????*?產(chǎn)品數(shù)量
?????*/
????private?Integer?productCount;
????/**
?????*?產(chǎn)品評(píng)論數(shù)量
?????*/
????private?Integer?productCommentCount;
????/**
?????*?品牌logo
?????*/
????private?String?logo;
????/**
?????*?專區(qū)大圖
?????*/
????private?String?bigPic;
????/**
?????*?品牌故事
?????*/
????private?String?brandStory;
????//省略getter、setter方法
}
再來看下Controller中代碼，我們同樣規(guī)范地在方法上添加了注釋，生成API文檔的時(shí)候也自動(dòng)有了；
/**
?*?商品品牌管理
?*/
@Controller
@RequestMapping("/brand")
public?class?PmsBrandController?{
????@Autowired
????private?PmsBrandService?brandService;
????
????/**
?????*?分頁查詢品牌列表
?????*
?????*?@param?pageNum?頁碼
?????*?@param?pageSize?分頁大小
?????*/
????@RequestMapping(value?=?"/list",?method?=?RequestMethod.GET)
????@ResponseBody
????@PreAuthorize("hasRole('ADMIN')")
????public?CommonResult>?listBrand(@RequestParam(value?=?"pageNum",?defaultValue?=?"1")
????????????????????????????????????????????????????????????????Integer?pageNum,
????????????????????????????????????????????????????????@RequestParam(value?=?"pageSize",?defaultValue?=?"3")
????????????????????????????????????????????????????????????????Integer?pageSize)?{
????????List?brandList?=?brandService.listBrand(pageNum,?pageSize);
????????return?CommonResult.success(CommonPage.restPage(brandList));
????}
}
當(dāng)然
smart-doc還提供了自定義注釋tag，用于增強(qiáng)文檔功能；@ignore：生成文檔時(shí)是否要過濾該屬性； @required：用于修飾接口請(qǐng)求參數(shù)是否必須； @since：用于修飾接口中屬性添加的版本號(hào)。 為了寫出優(yōu)雅的API文檔接口，我們經(jīng)常會(huì)對(duì)返回結(jié)果進(jìn)行統(tǒng)一封裝，
smart-doc也支持這樣的設(shè)置，在smart-doc.json中添加如下配置即可；
{
??"responseBodyAdvice":{?//統(tǒng)一返回結(jié)果設(shè)置
????"className":"com.macro.mall.tiny.common.api.CommonResult"?//對(duì)應(yīng)封裝類
??}
}
我們也經(jīng)常會(huì)用枚舉類型來封裝狀態(tài)碼，在 smart-doc.json中添加如下配置即可；
{
??"errorCodeDictionaries":?[{?//錯(cuò)誤碼列表設(shè)置
????"title":?"title",
????"enumClassName":?"com.macro.mall.tiny.common.api.ResultCode",?//錯(cuò)誤碼枚舉類
????"codeField":?"code",?//錯(cuò)誤碼對(duì)應(yīng)字段
????"descField":?"message"?//錯(cuò)誤碼描述對(duì)應(yīng)字段
??}]
}
配置成功后，即可在API文檔中生成 錯(cuò)誤碼列表；
有時(shí)候我們也會(huì)想給某些接口添加自定義請(qǐng)求頭，比如給一些需要登錄的接口添加 Authorization頭，在smart-doc.json中添加如下配置即可；
{
??"requestHeaders":?[{?//請(qǐng)求頭設(shè)置
????"name":?"Authorization",?//請(qǐng)求頭名稱
????"type":?"string",?//請(qǐng)求頭類型
????"desc":?"token請(qǐng)求頭的值",?//請(qǐng)求頭描述
????"value":"token請(qǐng)求頭的值",?//請(qǐng)求頭的值
????"required":?false,?//是否必須
????"since":?"-",?//添加版本
????"pathPatterns":?"/brand/**",?//哪些路徑需要添加請(qǐng)求頭
????"excludePathPatterns":"/admin/login"?//哪些路徑不需要添加請(qǐng)求頭
??}]
}
配置成功后，在接口文檔中即可查看到自定義請(qǐng)求頭信息了。
使用Postman測(cè)試接口
我們使用Swagger生成文檔時(shí)候，是可以直接在上面測(cè)試接口的，而
smart-doc的接口測(cè)試能力真的很弱，這也許是它擁抱Postman的原因吧，畢竟Postman是非常好用的接口測(cè)試工具，下面我們來結(jié)合Postman使用下！
smart-doc內(nèi)置了Postman的json生成插件，可以一鍵生成并導(dǎo)入到Postman中去，雙擊smart-doc:postman按鈕即可生成；
此時(shí)將在項(xiàng)目的 static/doc目錄下生成postman.json文件；
將 postman.json文件直接導(dǎo)入到Postman中即可使用；
導(dǎo)入成功后，所有接口都將在Postman中顯示，這下我們可以愉快地測(cè)試接口了！
總結(jié)
smart-doc確實(shí)是一款好用的API文檔生成工具，尤其是它零注解侵入的特點(diǎn)。雖然它的接口測(cè)試能力有所不足，但是可以一鍵生成JSON文件并導(dǎo)入到Postman中去，使用起來也是非常方便的！
參考資料
官方文檔：https://gitee.com/smart-doc-team/smart-doc/wikis/HOME
項(xiàng)目源碼地址
https://github.com/macrozheng/mall-learning/tree/master/mall-tiny-smart-doc
推薦閱讀
阿里某leader因年輕下屬不主動(dòng)找活干，提醒對(duì)方繼續(xù)這樣績效不好看，對(duì)方竟直接辭職！
女程序員做了個(gè)夢(mèng)，神評(píng)論。。。
火遍全國的網(wǎng)絡(luò)熱梗“yyds”，創(chuàng)造者被判刑3年
END
頂級(jí)程序員：topcoding
做最好的程序員社區(qū)：Java后端開發(fā)、Python、大數(shù)據(jù)、AI
一鍵三連「分享」、「點(diǎn)贊」和「在看」