傳統swagger（之前在用）接口文檔的缺點：
1、代碼侵入性太強。
2、寫着麻煩。需要寫大量的注解，太麻煩！
smart-doc的優點：
1、不需要注解，無侵入性。
2、只需要寫好注釋即可，界面也比較美觀。
3、對一些常用的電話、地址之類的模擬的數據跟真的一樣（哈哈哈）。
4、可以生成Markdown、HTML5等多種文檔格式。
以下是官方對其描述的一些特性：
零注解、零學習成本、只需要寫標准java注釋。
基於源代碼接口定義自動推導，強大的返回結構推導。
支持Spring MVC,Spring Boot,Spring Boot Web Flux(controller書寫方式)。
支持Callable,Future,CompletableFuture等異步接口返回的推導。
支持JavaBean上的JSR303參數校驗規范。 對json請求參數的接口能夠自動生成模擬json參數。
對一些常用字段定義能夠生成有效的模擬值。
支持生成json返回值示例。
支持從項目外部加載源代碼來生成字段注釋(包括標准規范發布的jar包)。
支持生成多種格式文檔：Markdown、HTML5、Asciidoctor、Postman Collection。
輕易實現在Spring Boot服務上在線查看靜態HTML5 api文檔。
開放文檔數據，可自由實現接入文檔管理系統。
支持生成dubbo rpc文檔。
使用示例
一、maven插件（推薦）
1、引入依賴
<plugin>
<groupId>com.github.shalousun</groupId>
<artifactId>smart-doc-maven-plugin</artifactId>
<version>1.1.9</version>
<configuration>
<!--指定生成文檔的使用的配置文件,配置文件放在自己的項目中-->
<configFile>./src/main/resources/smart-doc.json</configFile>
<!--指定項目名稱-->
<projectName>UU跑腿廣告服務中心文檔</projectName>
</configuration>
<executions>
<execution>
<goals>
<goal>html</goal>
</goals>
</execution>
</executions>
</plugin>
2、添加smart-doc生成文檔的配置
{ "serverUrl": "http://127.0.0.1", //設置服務器地址,非必須 "isStrict": false, //是否開啟嚴格模式 "allInOne": true, //是否將文檔合並到一個文件中，一般推薦為true "outPath": "D://md2", //指定文檔的輸出路徑 "coverOld": true, //是否覆蓋舊的文件，主要用於mardown文件覆蓋 "packageFilters": "",//controller包過濾，多個包用英文逗號隔開 "md5EncryptedHtmlName": false,//只有每個controller生成一個html文件是才使用 "projectName": "smart-doc",//配置自己的項目名稱 "skipTransientField": true,//目前未實現 "showAuthor":true,//是否顯示接口作者名稱，默認是true,不想顯示可關閉 "requestFieldToUnderline":true, //自動將駝峰入參字段在文檔中轉為下划線格式,//@since 1.8.7 版本開始 "responseFieldToUnderline":true,//自動將駝峰入參字段在文檔中轉為下划線格式,//@since 1.8.7 版本開始 "inlineEnum":true,//設置為true會將枚舉詳情展示到參數表中，默認關閉，//@since 1.8.8版本開始 "recursionLimit":7,//設置允許遞歸執行的次數用於避免棧溢出，默認是7，正常為3次以內，//@since 1.8.8版本開始 "ignoreRequestParams":[ //忽略請求參數對象，把不想生成文檔的參數對象屏蔽掉，@since 1.9.2 "org.springframework.ui.ModelMap" ], "dataDictionaries": [ //配置數據字典，沒有需求可以不設置 { "title": "http狀態碼字典", //數據字典的名稱 "enumClassName": "com.power.common.enums.HttpCodeEnum", //數據字典枚舉類名稱 "codeField": "code",//數據字典字典碼對應的字段名稱 "descField": "message"//數據字典對象的描述信息字典 } ], "errorCodeDictionaries": [{ //錯誤碼列表，沒有需求可以不設置 "title": "title", "enumClassName": "com.power.common.enums.HttpCodeEnum", //錯誤碼枚舉類,如果是枚舉是在一個類中定義則用$鏈接類BaseErrorCode$Common "codeField": "code",//錯誤碼的code碼字段名稱 "descField": "message"//錯誤碼的描述信息對應的字段名 }], "revisionLogs": [ //設置文檔變更記錄，沒有需求可以不設置 { "version": "1.0", //文檔版本號 "status": "update", //變更操作狀態，一般為：創建、更新等 "author": "author", //文檔變更作者
"revisionTime": "2020-09-24", //變更時間 "remarks": "desc" //變更描述 } ], "customResponseFields": [ //自定義添加字段和注釋，api-doc后期遇到同名字段則直接給相應字段加注釋，非必須 { "name": "code",//覆蓋響應碼字段 "desc": "響應代碼",//覆蓋響應碼的字段注釋 "value": "00000"//設置響應碼的值 } ], "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" }], "sourceCodePaths": [ //設置代碼路徑，smart-doc默認會自動加載src/main/java, 沒有需求可以不設置 1.0.0以后版本此配置不再生效 { "path": "src/main/java", "desc": "測試" } ] }
3、運行插件生成文檔
最后通過ip和端口號訪問即可。
二、測試類方式
1、引入依賴
<dependency>
<groupId>com.github.shalousun</groupId>
<artifactId>smart-doc</artifactId>
<version>1.8.7</version>
<scope>test</scope>
</dependency>
2、每個項目建議都寫一個測試類
import com.power.common.util.DateTimeUtil; import com.power.doc.builder.ApiDocBuilder; import com.power.doc.builder.HtmlApiDocBuilder; import com.power.doc.constants.DocGlobalConstants; import com.power.doc.model.*; import lombok.extern.slf4j.Slf4j; import org.junit.Test; import org.junit.runner.RunWith; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.test.context.SpringBootTest; import org.springframework.test.context.junit4.SpringRunner; import java.util.ArrayList; import java.util.HashMap; import java.util.List; import java.util.Map; /** * @author qyy * @title: SpringBootTest * @projectName pt * @description: api文檔生成測試 * @date 2020/1/7 000710:15 */ @RunWith(SpringRunner.class) @SpringBootTest @Slf4j public class SpringBootTest { @Test public void testBuilderMdControllersApi() { ApiConfig config = new ApiConfig(); config.setServerUrl("http://localhost:8080"); //設置為嚴格模式，Smart-doc將降至要求每個Controller暴露的接口寫上標准文檔注釋 //config.setStrict(true); config.setStrict(false); //當把AllInOne設置為true時，Smart-doc將會把所有接口生成到一個Markdown、HHTML或者AsciiDoc中 config.setAllInOne(true); //Set the api document output path. config.setOutPath("d:\\md"); // 設置接口包掃描路徑過濾，如果不配置則Smart-doc默認掃描所有的接口類 // 配置多個報名有英文逗號隔開 // config.setPackageFilters("com.power.doc.controller"); //since 1.7.5 //如果該選項的值為false,則smart-doc生成allInOne.md文件的名稱會自動添加版本號 config.setCoverOld(true); //since 1.7.5 //設置項目名(非必須)，如果不設置會導致在使用一些自動添加標題序號的工具顯示的序號不正常 config.setProjectName("XXXXX接口文檔"); //設置公共請求頭.如果不需要請求頭，則無需設置 config.setRequestHeaders( ApiReqHeader.header().setName("access_token").setType("string") .setDesc("Basic auth credentials").setRequired(true).setSince("v1.1.0"), ApiReqHeader.header().setName("user_uuid").setType("string").setDesc("User Uuid key") ); long start = System.currentTimeMillis(); //生成Markdown文件 ApiDocBuilder.buildApiDoc(config); long end = System.currentTimeMillis(); DateTimeUtil.printRunTime(end, start); } @Test public void testBuilderHtmlControllersApi() { ApiConfig config = new ApiConfig(); config.setServerUrl("http://192.168.6.110:8080"); //設置為嚴格模式，Smart-doc將降至要求每個Controller暴露的接口寫上標准文檔注釋 config.setStrict(false); //當把AllInOne設置為true時，Smart-doc將會把所有接口生成到一個Markdown、HHTML或者AsciiDoc中 config.setAllInOne(true); //HTML5文檔，建議直接放到src/main/resources/static/doc下，Smart-doc提供一個配置常量HTML_DOC_OUT_PATH config.setOutPath(DocGlobalConstants.HTML_DOC_OUT_PATH); config.setProjectName("XXXXXX接口文檔"); // 設置接口包掃描路徑過濾，如果不配置則Smart-doc默認掃描所有的接口類 // 配置多個報名有英文逗號隔開 //config.setPackageFilters("com.power.doc.controller"); //設置公共請求頭.如果不需要請求頭，則無需設置 // config.setRequestHeaders( // ApiReqHeader.header().setName("access_token").setType("string") // .setDesc("Basic auth credentials").setRequired(true).setSince("v1.1.0"), // ApiReqHeader.header().setName("user_uuid").setType("string").setDesc("User Uuid key") // ); //設置錯誤錯列表，遍歷自己的錯誤碼設置給Smart-doc即可 // List<ApiErrorCode> errorCodeList = new ArrayList<>(); // for (ErrorCodeEnum codeEnum : ErrorCodeEnum.values()) { // ApiErrorCode errorCode = new ApiErrorCode(); // errorCode.setValue(codeEnum.getCode()).setDesc(codeEnum.getDesc()); // errorCodeList.add(errorCode); // } // //不需要顯示錯誤碼，則可以設置 // config.setErrorCodes(errorCodeList); long start = System.currentTimeMillis(); //生成HTML5文件 HtmlApiDocBuilder.buildApiDoc(config); long end = System.currentTimeMillis(); DateTimeUtil.printRunTime(end, start); } }
3、測試生成接口文檔。
我這邊主要是生成的html接口文檔，生成之后會在項目\src\main\resources\static\doc這個目錄下，可以直接在瀏覽器輸入http://192.168.6.110:8080/doc/index.html#即可訪問。
4、注釋說明
一定要寫java注釋,注釋如下參考：
/** * id */ private Integer id;