還在用Swagger？試試這款零注解侵入的API文檔生成工具，跟Postman絕配！
點擊關(guān)注公眾號，Java干貨及時送達
前后端接口聯(lián)調(diào)需要API文檔，我們經(jīng)常會使用工具來生成。之前經(jīng)常使用Swagger來生成，最近發(fā)現(xiàn)一款好用的API文檔生成工具
smart-doc, 它有著很多Swagger不具備的特點，推薦給大家。
聊聊Swagger
在我們使用Swagger的時候，經(jīng)常會需要用到它的注解，比如@Api、@ApiOperation這些，Swagger通過它們來生成API文檔。比如下面的代碼：
Swagger對代碼的入侵性比較強，有時候代碼注釋和注解中的內(nèi)容有點重復(fù)了。有沒有什么工具能實現(xiàn)零注解入侵，直接根據(jù)代碼注釋生成API文檔呢？smart-doc恰好是這種工具！
smart-doc簡介
smart-doc是一款A(yù)PI文檔生成工具，無需多余操作，只要你規(guī)范地寫好代碼注釋，就能生成API文檔。同時能直接生成Postman調(diào)試文件，一鍵導(dǎo)入Postman即可調(diào)試，非常好用！
smart-doc具有如下優(yōu)點：
生成API文檔
接下來我們把
smart-doc集成到SpringBoot項目中，體驗一下它的API文檔生成功能。
首先我們需要在項目中添加 smart-doc的Maven插件，可以發(fā)現(xiàn)smart-doc就是個插件，連依賴都不用添加，真正零入侵啊；
<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>
接下來在項目的 resources目錄下，添加配置文件smart-doc.json，屬性說明直接參考注釋即可；
{
??"serverUrl":?"http://localhost:8088",?//指定后端服務(wù)訪問地址
??"outPath":?"src/main/resources/static/doc",?//指定文檔的輸出路徑，生成到項目靜態(tài)文件目錄下，隨項目啟動可以查看
??"isStrict":?false,?//是否開啟嚴(yán)格模式
??"allInOne":?true,?//是否將文檔合并到一個文件中
??"createDebugPage":?false,?//是否創(chuàng)建可以測試的html頁面
??"packageFilters":?"com.macro.mall.tiny.controller.*",?//controller包過濾
??"style":"xt256",?//基于highlight.js的代碼高設(shè)置
??"projectName":?"mall-tiny-smart-doc",?//配置自己的項目名稱
??"showAuthor":false,?//是否顯示接口作者名稱
??"allInOneDocFileName":"index.html"?//自定義設(shè)置輸出文檔名稱
}
打開IDEA的Maven面板，雙擊 smart-doc插件的smart-doc:html按鈕，即可生成API文檔；
此時我們可以發(fā)現(xiàn)，在項目的 static/doc目錄下已經(jīng)生成如下文件；
運行項目，訪問生成的API接口文檔，發(fā)現(xiàn)文檔非常詳細(xì)，包括了請求參數(shù)和響應(yīng)結(jié)果的各種說明，訪問地址：http://localhost:8088/doc/index.html
我們回過來看下實體類的代碼，可以發(fā)現(xiàn)我們只是規(guī)范地添加了字段注釋，生成文檔的時候就自動有了；
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)品評論數(shù)量
?????*/
????private?Integer?productCommentCount;
????/**
?????*?品牌logo
?????*/
????private?String?logo;
????/**
?????*?專區(qū)大圖
?????*/
????private?String?bigPic;
????/**
?????*?品牌故事
?????*/
????private?String?brandStory;
????//省略getter、setter方法
}
再來看下Controller中代碼，我們同樣規(guī)范地在方法上添加了注釋，生成API文檔的時候也自動有了；
/**
?*?商品品牌管理
?*/
@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，用于增強文檔功能；@ignore：生成文檔時是否要過濾該屬性； @required：用于修飾接口請求參數(shù)是否必須； @since：用于修飾接口中屬性添加的版本號。 為了寫出優(yōu)雅的API文檔接口，我們經(jīng)常會對返回結(jié)果進行統(tǒng)一封裝，
smart-doc也支持這樣的設(shè)置，在smart-doc.json中添加如下配置即可；
{
??"responseBodyAdvice":{?//統(tǒng)一返回結(jié)果設(shè)置
????"className":"com.macro.mall.tiny.common.api.CommonResult"?//對應(yīng)封裝類
??}
}
我們也經(jīng)常會用枚舉類型來封裝狀態(tài)碼，在 smart-doc.json中添加如下配置即可；
{
??"errorCodeDictionaries":?[{?//錯誤碼列表設(shè)置
????"title":?"title",
????"enumClassName":?"com.macro.mall.tiny.common.api.ResultCode",?//錯誤碼枚舉類
????"codeField":?"code",?//錯誤碼對應(yīng)字段
????"descField":?"message"?//錯誤碼描述對應(yīng)字段
??}]
}
配置成功后，即可在API文檔中生成 錯誤碼列表；
有時候我們也會想給某些接口添加自定義請求頭，比如給一些需要登錄的接口添加 Authorization頭，在smart-doc.json中添加如下配置即可；
{
??"requestHeaders":?[{?//請求頭設(shè)置
????"name":?"Authorization",?//請求頭名稱
????"type":?"string",?//請求頭類型
????"desc":?"token請求頭的值",?//請求頭描述
????"value":"token請求頭的值",?//請求頭的值
????"required":?false,?//是否必須
????"since":?"-",?//添加版本
????"pathPatterns":?"/brand/**",?//哪些路徑需要添加請求頭
????"excludePathPatterns":"/admin/login"?//哪些路徑不需要添加請求頭
??}]
}
配置成功后，在接口文檔中即可查看到自定義請求頭信息了。
使用Postman測試接口
我們使用Swagger生成文檔時候，是可以直接在上面測試接口的，而
smart-doc的接口測試能力真的很弱，這也許是它擁抱Postman的原因吧，畢竟Postman是非常好用的接口測試工具，下面我們來結(jié)合Postman使用下！
smart-doc內(nèi)置了Postman的json生成插件，可以一鍵生成并導(dǎo)入到Postman中去，雙擊smart-doc:postman按鈕即可生成；
此時將在項目的 static/doc目錄下生成postman.json文件；
將 postman.json文件直接導(dǎo)入到Postman中即可使用；
導(dǎo)入成功后，所有接口都將在Postman中顯示，這下我們可以愉快地測試接口了！
總結(jié)
smart-doc確實是一款好用的API文檔生成工具，尤其是它零注解侵入的特點。雖然它的接口測試能力有所不足，但是可以一鍵生成JSON文件并導(dǎo)入到Postman中去，使用起來也是非常方便的！
參考資料
官方文檔：https://gitee.com/smart-doc-team/smart-doc/wikis/HOME
項目源碼地址
https://github.com/macrozheng/mall-learning/tree/master/mall-tiny-smart-doc
往 期 推 薦
1、致歉！抖音Semi Design承認(rèn)參考阿里Ant Design
2、對比7種分布式事務(wù)方案，還是偏愛阿里開源的Seata，真香！
點分享
點收藏
點點贊
點在看
