傳統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", //檔案變更作者 "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;
5、效果請查看官網所示
https://gitee.com/smart-doc-team/smart-doc/wikis/%E6%96%87%E6%A1%A3%E6%95%88%E6%9E%9C%E5%9B%BE?sort_id=1652819
轉載請註明出處，本文鏈接：https://www.uj5u.com/houduan/119895.html
標籤：Java