1，基于maven項目來完成smart-doc接口文檔的生成
在pom.xml文件添加插件依賴
<plugin>
<groupId>com.github.shalousun</groupId>
<artifactId>smart-doc-maven-plugin</artifactId>
<version>2.0.1</version>
<configuration>
<!--指定生成文檔使用的配置文件-->
<configFile>./src/main/resources/smart-doc.json</configFile>
<projectName>測試</projectName>
</configuration>
<executions>
<execution>
<!--不需要在編譯項目時自動生成文檔可注釋phase-->
<phase>compile</phase>
<goals>
<goal>html</goal>
</goals>
</execution>
</executions>
</plugin>
2，指定生成文檔的json配置文件
如上：在resources目錄新建一個json文件，該文件主要提供接口地址，接口請求頭，請求公共參數(shù)，響應公共參數(shù)，響應碼文件的配置。
這里提供一份文件參考：
{
? "serverUrl": "http://127.0.0.1", //設置服務器地址,非必須
? "isStrict": false, //是否開啟嚴格模式
? "allInOne": true,? //是否將文檔合并到一個文件中，一般推薦為true
? "outPath": "D://md2", //指定文檔的輸出路徑
? "coverOld": true,? //是否覆蓋舊的文件，主要用于mardown文件覆蓋
? "packageFilters": "",//controller包過濾，多個包用英文逗號隔開
? "style":"xt256", //基于highlight.js的代碼高亮設置，喜歡配色統(tǒng)一簡潔的同學可以不設置
? "createDebugPage": true,//@since 2.0.0 smart-doc支持創(chuàng)建可以測試的html頁面，僅在AllInOne模式中起作用。
? "md5EncryptedHtmlName": false,//只有每個controller生成一個html文件是才使用
? "projectName": "smart-doc",//配置自己的項目名稱
? "skipTransientField": true,//目前未實現(xiàn)
? "showAuthor":true,//是否顯示接口作者名稱，默認是true,不想顯示可關閉
? "requestFieldToUnderline":true, //自動將駝峰入?yún)⒆侄卧谖臋n中轉(zhuǎn)為下劃線格式,//@since 1.8.7 版本開始
? "responseFieldToUnderline":true,//自動將駝峰入?yún)⒆侄卧谖臋n中轉(zhuǎn)為下劃線格式,//@since 1.8.7 版本開始
? "inlineEnum":true,//設置為true會將枚舉詳情展示到參數(shù)表中，默認關閉，//@since 1.8.8版本開始
? "recursionLimit":7,//設置允許遞歸執(zhí)行的次數(shù)用于避免棧溢出，默認是7，正常為3次以內(nèi)，//@since 1.8.8版本開始
? "displayActualType":false,//配置true會在注釋欄自動顯示泛型的真實類型短類名，@since 1.9.6
? "ignoreRequestParams":[ //忽略請求參數(shù)對象，把不想生成文檔的參數(shù)對象屏蔽掉，@since 1.9.2
? ? ? "org.springframework.ui.ModelMap"
? ],
? "dataDictionaries": [ //配置數(shù)據(jù)字典，沒有需求可以不設置
? ? {
? ? ? "title": "http狀態(tài)碼字典", //數(shù)據(jù)字典的名稱
? ? ? "enumClassName": "com.power.common.enums.HttpCodeEnum", //數(shù)據(jù)字典枚舉類名稱
? ? ? "codeField": "code",//數(shù)據(jù)字典字典碼對應的字段名稱
? ? ? "descField": "message"http://數(shù)據(jù)字典對象的描述信息字典
? ? }
? ],
? "errorCodeDictionaries": [{ //錯誤碼列表，沒有需求可以不設置
? ? "title": "title",
? ? "enumClassName": "com.power.common.enums.HttpCodeEnum", //錯誤碼枚舉類,如果是枚舉是在一個類中定義則用$鏈接類BaseErrorCode$Common
? ? "codeField": "code",//錯誤碼的code碼字段名稱
? ? "descField": "message"http://錯誤碼的描述信息對應的字段名
? }],
? "revisionLogs": [ //設置文檔變更記錄，沒有需求可以不設置
? ? {
? ? ? "version": "1.0", //文檔版本號
? ? ? "revisionTime":"2020-12-31 10:30",//文檔修訂時間
? ? ? "status": "update", //變更操作狀態(tài)，一般為：創(chuàng)建、更新等
? ? ? "author": "author", //文檔變更作者
? ? ? "remarks": "desc" //變更描述
? ? }
? ],
? "customResponseFields": [ //自定義添加字段和注釋，api-doc后期遇到同名字段則直接給相應字段加注釋，非必須
? ? {
? ? ? "name": "code",//覆蓋響應碼字段
? ? ? "desc": "響應代碼",//覆蓋響應碼的字段注釋
? ? ? "ownerClassName": "org.springframework.data.domain.Pageable", //指定你要添加注釋的類名
? ? ? "value": "00000"http://設置響應碼的值
? ? }
? ],
? "requestHeaders": [ //設置請求頭，沒有需求可以不設置
? ? {
? ? ? "name": "token",
? ? ? "type": "string",
? ? ? "desc": "desc",
? ? ? "required": false,
? ? ? "value":"55",
? ? ? "since": "-"
? ? }
? ],
? "rpcApiDependencies":[{ // 項目開放的dubbo api接口模塊依賴，配置后輸出到文檔方便使用者集成
? ? ? "artifactId":"SpringBoot2-Dubbo-Api",
? ? ? "groupId":"com.demo",
? ? ? "version":"1.0.0"
? }],
? "rpcConsumerConfig":"src/main/resources/consumer-example.conf",//文檔中添加dubbo consumer集成配置，用于方便集成方可以快速集成
? "apiObjectReplacements": [{ // 自smart-doc 1.8.5開始你可以使用自定義類覆蓋其他類做文檔渲染，使用全類名
? ? ? "className": "org.springframework.data.domain.Pageable",
? ? ? "replacementClassName": "com.power.doc.model.PageRequestDto" //自定義的PageRequestDto替換Pageable做文檔渲染
? }],
? "apiConstants": [{//從1.8.9開始配置自己的常量類，smart-doc在解析到常量時自動替換為具體的值,如：http://localhost:8080/testConstants/+ApiVersion.VERSION中的ApiVersion.VERSION會被替換
? ? ? "constantsClassName": "com.power.doc.constants.RequestParamConstant"
? }],
? "responseBodyAdvice":{ //自smart-doc 1.9.8起，ResponseBodyAdvice統(tǒng)一返回設置，可用ignoreResponseBodyAdvice tag來忽略
? ? ? "className":"com.power.common.model.CommonResult" //通用響應體
? },
? "sourceCodePaths": [ //設置代碼路徑，smart-doc默認會自動加載src/main/java, 沒有需求可以不設置 1.0.0以后版本此配置不再生效
? ? {
? ? ? "path": "src/main/java",
? ? ? "desc": "測試"
? ? }
? ]
}
3，通過上面兩個步驟完成了smart-doc文檔的配置，最后補上請求接口注釋和實體類注釋即可
接口文檔通過掃描注解@RequestMapping識別模塊,@PostMapping,@GetMapping識別接口，通過注釋來完成接口文檔的編寫。
4，最后通過maven命令完成文檔構(gòu)建，我這里通過idea自帶工具完成構(gòu)建
5，最后完成效果圖
