建站
咨詢
售后
建站咨詢
新聞中心
哈嘍，大家好，我是了不起。
成都創(chuàng)新互聯(lián)主要為客戶提供服務(wù)項目涵蓋了網(wǎng)頁視覺設(shè)計、VI標志設(shè)計、全網(wǎng)整合營銷推廣、網(wǎng)站程序開發(fā)、HTML5響應(yīng)式重慶網(wǎng)站建設(shè)公司、手機網(wǎng)站制作設(shè)計、微商城、網(wǎng)站托管及成都網(wǎng)站改版、WEB系統(tǒng)開發(fā)、域名注冊、國內(nèi)外服務(wù)器租用、視頻、平面設(shè)計、SEO優(yōu)化排名。設(shè)計、前端、后端三個建站步驟的完善服務(wù)體系。一人跟蹤測試的建站服務(wù)標準。已經(jīng)為電動窗簾行業(yè)客戶提供了網(wǎng)站維護服務(wù)。
首先，Swagger 這個工具能夠自動生成 API 接口文檔，在線調(diào)試，節(jié)省了很多書寫文檔的時間，非常強大。
但是，想要文檔生成的合格，還是要書寫大量的注解。有沒有一種連注解都不用寫的方式呢？
smart-doc簡介
今天了不起給大家推薦一個技術(shù)：smart-doc，看名字就知道，它是 智能-文檔。直接分析代碼，根據(jù)代碼含義生成文檔（開個玩笑，它還沒有那么智能）；其實它是利用的注釋，來生成文檔，還是需要寫注釋的。
官方介紹：smart-doc是一款同時支持JAVA REST API和Apache Dubbo RPC接口文檔生成的工具，smart-doc在業(yè)內(nèi)率先提出基于JAVA泛型定義推導的理念， 完全基于接口源碼來分析生成接口文檔，不采用任何注解侵入到業(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()這個注解，徒增學習成本
使用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 -> 接口導入 -> 自動同步
這個數(shù)據(jù)源URL可以直接配置為 file:///D:/111/openapi.json，在你配置pom的時候，直接配置成編譯項目時生成 openapi格式的文檔，就可以自動部署到apifox，完美~
小結(jié)
今天了不起對這個smart-doc就介紹到這里了，感興趣的小伙伴可以用起來了，對代碼0侵入，簡直太適合我這種強迫癥患者了。
文章標題：真的別再用Swagger了，你知道為什么嗎？
網(wǎng)址分享：http://www.dlmjj.cn/article/dhsgpsh.html
