2023-06-26 17:13:36來源:Java技術(shù)指北
哈嘍,大家好,我是了不起。
首先,Swagger 這個工具能夠自動生成 API 接口文檔,在線調(diào)試,節(jié)省了很多書寫文檔的時間,非常強大。
但是,想要文檔生成的合格,還是要書寫大量的注解。有沒有一種連注解都不用寫的方式呢?
(資料圖片)
今天了不起給大家推薦一個技術(shù):smart-doc,看名字就知道,它是 智能-文檔。直接分析代碼,根據(jù)代碼含義生成文檔(開個玩笑,它還沒有那么智能);其實它是利用的注釋,來生成文檔,還是需要寫注釋的。
官方介紹:smart-doc是一款同時支持JAVA REST API和Apache Dubbo RPC接口文檔生成的工具,smart-doc在業(yè)內(nèi)率先提出基于JAVA泛型定義推導(dǎo)的理念, 完全基于接口源碼來分析生成接口文檔,不采用任何注解侵入到業(yè)務(wù)代碼中。你只需要按照java-doc標準編寫注釋, smart-doc就能幫你生成一個簡易明了的Markdown、HTML5、Postman Collection2.0+、OpenAPI 3.0+的文檔。
swagger和smart-doc的對比我們來看看swagger和smart-doc的區(qū)別
來看看smart-doc 的代碼
如果是swagger 的寫法,每個字段都要加上@ApiModelProperty("xxx")的注解,如果有幾十個字段,幾十個類,那代碼量多的可不小。
不過這些類一般都是自動生成工具生成的,對寫代碼的人影響不大,不過這樣子寫倒是簡潔了不少,甚得我意~
可能有人就說了,我不寫注釋,只寫swagger注解,看起來也很簡潔,這也確實沒錯。
確實看起來很簡潔,不過沒有文檔注釋的情況下,在其他類里你是看不到這個字段的解釋的,每次找字段都得回到這個類看看到底是不是這個字段。如果你和同事們的英語都 very good,當我沒說。
如果是api接口,smart-doc想要生成文檔,需要寫成這樣(好像看起來什么都沒寫)
而swagger就需要加上@ApiOperation()這個注解,如果是個參數(shù)多的接口,還需要@ApiImplicitParams()這個注解,徒增學(xué)習(xí)成本
使用smart-doc總共需要3步:
1.引入pom依賴,是一個插件
com.github.shalousun smart-doc-maven-plugin ${smart-doc-plugin.version} ${basedir}/src/main/resources/smart-doc.json ${project.name} com.fu:common-.* com.fu:generator compile openapi
2.編寫smart-doc.json文件
{ // 參考文檔:https://smart-doc-group.github.io/#/zh-cn/start/quickstart "outPath": "D:\\111", "coverOld": true, "allInOne": true, // 是否將文檔合并到一個文件中,一般推薦為true "createDebugPage": true,//@since 2.0.0 smart-doc支持創(chuàng)建可以測試的html頁面,僅在AllInOne模式中起作用。 "isStrict": false, //是否開啟嚴格模式 // controller包過濾,多個包用英文逗號隔開 "packageFilters": "com.fu.system.controller.*", "projectName": "system", "sortByTitle": true, // 接口排序 "ignoreRequestParams":[ //忽略請求參數(shù)對象,把不想生成文檔的參數(shù)對象屏蔽掉,@since 1.9.2 "javax.servlet.http.HttpServletRequest", "javax.servlet.http.HttpServletResponse", "javax.servlet.http.HttpSession" ]}
3.運行這個插件,如果很熟悉mvn命令,在命令行運行它也行;可以生成openapi、postman、html、Markdown等各種格式的文檔
關(guān)于pom 和 smart-doc.json 的配置,具體配置可前往官方文檔查看:
https://smart-doc-group.github.io/#/zh-cn/?id=smart-doc
文檔自動化如果它不能和swagger一樣,自動部署文檔,還得手動,那也不會來推薦這個了。
官方推薦方式:smart-doc + Torna
需要額外部署一個 Torna 文檔接口服務(wù),類似 yapi;很多企業(yè)也都是單獨部署的接口文檔服務(wù)。
可以看出來界面比swagger好太多了
了不起這里給大家另一種方案,本地自動部署,smart-doc + apifox(postman應(yīng)該也可以)
apifox -> 接口導(dǎo)入 -> 自動同步
這個數(shù)據(jù)源URL可以直接配置為file:///D:/111/openapi.json,在你配置pom的時候,直接配置成編譯項目時生成 openapi格式的文檔,就可以自動部署到apifox,完美~
小結(jié)今天了不起對這個smart-doc就介紹到這里了,感興趣的小伙伴可以用起來了,對代碼0侵入,簡直太適合我這種強迫癥患者了。
關(guān)鍵詞:
哈嘍,大家好,我是了不起。首先,Swagger這個工具能夠自動生成API接口
杭州亞運會已進入100天倒計時,代表中國參加亞運的“電競國家隊”終于
一場時隔26年的“世紀大和解”將長安馬自達送上了熱搜。6月25日晚間,
Jmeter錄制腳本原理腳本錄制時,Jmeter作為代理網(wǎng)關(guān),通過監(jiān)聽某個端口
大家好,我是前端西瓜哥,今天我們來了解WebGL的紋理對象(Texture)紋
Python是一門非常流行的編程語言,擁有豐富的第三方庫和工具,這些庫和
一、商業(yè)圈1 小米汽車售價曝光!起售不到15萬,續(xù)航800km日前媒體獲取
一項新的研究顯示,許多企業(yè)在重命名項目時,不知不覺地將其代碼庫的用
相信大家對水泥混凝土路面裂縫的處理與修復(fù),水泥混凝土路面裂縫處理方
智通財經(jīng)APP獲悉,有市場觀察人士預(yù)計,今年下半年,美股市場一些消費
2023年6月,是我國第22個“安全生產(chǎn)月”。黨中央高度重視安全生產(chǎn)工作
《我的幻想鄉(xiāng)》是一款由商星奕工作室開發(fā)制作的模擬經(jīng)營游戲新作,目前
一、碑林區(qū)公辦初中招生對象有碑林區(qū)戶籍或?qū)W籍的小學(xué)應(yīng)屆畢業(yè)生、隨遷
交易商品牌 產(chǎn)地交貨地最新報價液體重金屬捕捉劑 含量50%河南森蒂環(huán)保
1、宋遺民詩,由中國宋代入元代,而不肯仕元的宋代遺民之詩。2、。文章