天天看點
傳回

smart-doc開箱使用

簡介

smart-doc是一款同時支援JAVA REST API和Apache Dubbo RPC接口文檔生成的工具，smart-doc在業内率先提出基于JAVA泛型定義推導的理念， 完全基于接口源碼來分析生成接口文檔，不采用任何注解侵入到業務代碼中。你隻需要按照java-doc标準編寫注釋， smart-doc就能幫你生成一個簡易明了的Markdown、HTML5、Postman Collection2.0+、OpenAPI 3.0+的文檔

git : https://github.com/smart-doc-group/smart-doc/wiki

gitee: https://gitee.com/smart-doc-team/smart-doc#generated-document-example

特性

  • 零注解、零學習成本、隻需要寫标準JAVA注釋。
  • 基于源代碼接口定義自動推導，強大的傳回結構推導。
  • 支援Spring MVC、Spring Boot、Spring Boot Web Flux(controller書寫方式)、Feign。
  • 支援Callable、Future、CompletableFuture等異步接口傳回的推導。
  • 支援JavaBean上的JSR303參數校驗規範，包括分組驗證。
  • 對JSON請求參數的接口能夠自動生成模拟JSON參數。
  • 對一些常用字段定義能夠生成有效的模拟值。
  • 支援生成JSON傳回值示例。
  • 支援從項目外部加載源代碼來生成字段注釋(包括标準規範釋出的jar包)。
  • 支援生成多種格式文檔：Markdown、HTML5、Asciidoctor、Postman Collection、OpenAPI 3.0。 Up- 開放文檔資料，可自由實作接入文檔管理系統。
  • 支援導出錯誤碼和定義在代碼中的各種字典碼到接口文檔。
  • 支援Maven、Gradle插件式輕松內建。
  • 支援Apache Dubbo RPC接口文檔生成。
  • debug接口調試html5頁面完全支援檔案上傳，下載下傳(@download tag标記下載下傳方法)測試。

示例

https://gitee.com/smart-doc-team/smart-doc-example-cn

使用

1.Maven依賴添加

<plugin>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>[最新版本(目前2.2.7)]</version>
    <configuration>
        <!--指定生成文檔的使用的配置檔案,配置檔案放在自己的項目中-->
        <configFile>./src/main/resources/smart-doc.json</configFile>
        <!--指定項目名稱-->
        <projectName>測試</projectName>
        <!--smart-doc實作自動分析依賴樹加載第三方依賴的源碼，如果一些架構依賴庫加載不到導緻報錯，這時請使用excludes排除掉-->
        <excludes>
            <!--格式為：groupId:artifactId;參考如下-->
            <exclude>com.alibaba:fastjson</exclude>
        </excludes>
        <!--自1.0.8版本開始，插件提供includes支援,配置了includes後插件會按照使用者配置加載而不是自動加載，是以使用時需要注意-->
        <!--smart-doc能自動分析依賴樹加載所有依賴源碼，原則上會影響文檔建構效率，是以你可以使用includes來讓插件加載你配置的元件-->
        <includes>
            <!--格式為：groupId:artifactId;參考如下-->
            <!--也可以支援正則式如：com.alibaba:.* -->
            <include>com.alibaba:fastjson</include>
        </includes>
    </configuration>
    <executions>
        <execution>
            <!--如果不需要在執行編譯時啟動smart-doc，則将phase注釋掉-->
            <phase>compile</phase>
            <goals>
                <!--smart-doc提供了html、openapi、markdown等goal，可按需配置-->
                <goal>html</goal>
            </goals>
        </execution>
    </executions>
</plugin>

2.在項目中添加建立一個smart-doc.json配置檔案

{
   "outPath": "./src/main/resources/static/doc"
}

詳細配置說明

{
  "serverUrl": "http://127.0.0.1", //伺服器位址,非必須。導出postman建議設定成http://{{server}}友善直接在postman直接設定環境變量
  "pathPrefix": "", //設定path字首,非必須。如配置Servlet ContextPath 。@since 2.2.3
  "isStrict": false, //是否開啟嚴格模式
  "allInOne": true,  //是否将文檔合并到一個檔案中，一般推薦為true
  "outPath": "D://md2", //指定文檔的輸出路徑
  "coverOld": true,  //是否覆寫舊的檔案，主要用于mardown檔案覆寫
  "createDebugPage": true,//@since 2.0.0 smart-doc支援建立可以測試的html頁面，僅在AllInOne模式中起作用。
  "packageFilters": "",//controller包過濾，多個包用英文逗号隔開，2.2.2開始需要采用正則：com.test.controller.*
  "md5EncryptedHtmlName": false,//隻有每個controller生成一個html檔案是才使用
  "style":"xt256", //基于highlight.js的代碼高設定,可選值很多可檢視碼雲wiki，喜歡配色統一簡潔的同學可以不設定
  "projectName": "smart-doc",//配置自己的項目名稱
  "skipTransientField": true,//目前未實作
  "sortByTitle":false,//接口标題排序，預設為false,@since 1.8.7版本開始
  "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版本開始
  "allInOneDocFileName":"index.html",//自定義設定輸出文檔名稱, @since 1.9.0
  "requestExample":"true",//是否将請求示例展示在文檔中，預設true，@since 1.9.0
  "responseExample":"true",//是否将響應示例展示在文檔中，預設為true，@since 1.9.0
  "requestParamsTable": true, //是否将請求參數表展示在文檔中，預設true，@since 2.2.5
  "responseParamsTable": true //是否将響應參數表展示在文檔中, 預設true，@since 2.2.5
  "urlSuffix":".do",//支援SpringMVC舊項目的url字尾,@since 2.1.0
  "displayActualType":false,//配置true會在注釋欄自動顯示泛型的真實類型短類名，@since 1.9.6
  "appKey": "20201216788835306945118208",// torna平台對接appKey,, @since 2.0.9
  "appToken": "c16931fa6590483fb7a4e85340fcbfef", //torna平台appToken,@since 2.0.9
  "secret": "[email protected]#V&tUUYZR",//torna平台secret，@since 2.0.9
  "openUrl": "http://localhost:7700/api",//torna平台位址，填寫自己的私有化部署位址@since 2.0.9
  "debugEnvName":"測試環境", //torna環境名稱
  "debugEnvUrl":"http://127.0.0.1",//推送torna配置接口服務位址
  "tornaDebug":false,//啟用會推送日志
  "replace":true, // 推送文檔到torna強制替換 @since 2.2.4
  "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", //錯誤碼枚舉類
    "codeField": "code",//錯誤碼的code碼字段名稱
    "descField": "message"//錯誤碼的描述資訊對應的字段名
  }],
  "revisionLogs": [{ //文檔變更記錄，非必須
      "version": "1.0", //文檔版本号
      "revisionTime": "2020-12-31 10:30", //文檔修訂時間
      "status": "update", //變更操作狀态，一般為：建立、更新等
      "author": "author", //文檔變更作者
      "remarks": "desc" //變更描述
    }
  ],
  "customResponseFields": [{ //自定義添加字段和注釋，一般使用者處理第三方jar包庫，非必須
      "name": "code",//覆寫響應碼字段
      "desc": "響應代碼",//覆寫響應碼的字段注釋
      "ownerClassName": "org.springframework.data.domain.Pageable", //指定你要添加注釋的類名
      "ignore":true, //設定true會被自動忽略掉不會出現在文檔中
      "value": "00000"//設定響應碼的值
  }],
  "customRequestFields": [{ //自定義請求體的注釋，@since 2.1.3，非必須
       "name":"code", //屬性名
       "desc":"狀态碼", //描述
       "ownerClassName":"com.xxx.constant.entity.Result", //屬性對應的類全路徑
       "value":"200", //預設值或者mock值
       "required":true, //是否必填
       "ignore":false //是否忽略
  }],
  "requestHeaders": [{ //設定請求頭，沒有需求可以不設定
      "name": "token",//請求頭名稱
      "type": "string",//請求頭類型
      "desc": "desc",//請求頭描述資訊
      "value":"token請求頭的值",//不設定預設null
      "required": false,//是否必須
      "since": "-",//什麼版本添加的改請求頭
      "pathPatterns": "/app/test/**",//請看https://gitee.com/smart-doc-team/smart-doc/wikis/請求頭進階配置?sort_id=4178978
      "excludePathPatterns":"/app/page/**"//請看https://gitee.com/smart-doc-team/smart-doc/wikis/請求頭進階配置?sort_id=4178978
  },{
      "name": "appkey",//請求頭
      "type": "string",//請求頭類型
      "desc": "desc",//請求頭描述資訊
      "value":"appkey請求頭的值",//不設定預設null
      "required": false,//是否必須
      "pathPatterns": "/test/add,/testConstants/1.0",//正規表達式過濾請求頭,url比對上才會添加該請求頭，多個正則用分号隔開
      "since": "-"//什麼版本添加的改請求頭
  }],
  "requestParams": [ //公共請求參數(通過攔截器處理的場景)，@since 2.2.3,沒有需求請不要設定
    {
      "name": "configPathParam",//請求頭名稱
      "type": "string",//請求頭類型
      "desc": "desc",//請求頭描述資訊
      "paramIn": "path",
      "value":"testPath",//不設定預設null
      "required": false,//是否必須
      "since": "-",//什麼版本添加的改請求頭
      "pathPatterns": "*",//正規表達式過濾請求頭
      "excludePathPatterns":"/app/page/**" //參考請求頭中的用法
    },
    {
      "name": "configQueryParam",//請求頭名稱
      "type": "string",//請求頭類型
      "desc": "desc",//請求頭描述資訊
      "paramIn": "query",
      "value":"testQuery",//不設定預設null
      "required": false,//是否必須
      "since": "-",//什麼版本添加的改請求頭
      "pathPatterns": "*",//正規表達式過濾請求頭
      "excludePathPatterns":"/app/page/**"
    }
  ],
  "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在解析到常量時自動替換為具體的值，非必須
        "constantsClassName": "com.power.doc.constants.RequestParamConstant"
  }],
  "responseBodyAdvice":{ //自smart-doc 1.9.8起，非必須項，ResponseBodyAdvice統一傳回設定(不要随便配置根據項目的技術來配置)，可用ignoreResponseBodyAdvice tag來忽略
  		"className":"com.power.common.model.CommonResult" //通用響應體
  },
  "requestBodyAdvice":{ 自smart-doc 2.1.4 起，支援設定RequestBodyAdvice統一請求包裝類，非必須
         "className":"com.power.common.model.CommonResult"
  },
  "groups": [ // @since 2.2.5, 對不同的controller進行分組
    {
      "name": "測試分組",
      "apis": "com.power.doc.controller.app.*"
    }
  ]
}

3.生成文檔

指令式：

//生成html
mvn -Dfile.encoding=UTF-8 smart-doc:html
//生成markdown
mvn -Dfile.encoding=UTF-8 smart-doc:markdown
//生成adoc
mvn -Dfile.encoding=UTF-8 smart-doc:adoc
//生成postman json資料
mvn -Dfile.encoding=UTF-8 smart-doc:postman
// 生成 Open Api 3.0+,Since smart-doc-maven-plugin 1.1.5
mvn -Dfile.encoding=UTF-8 smart-doc:openapi
// 生成文檔推送到Torna平台
mvn -Dfile.encoding=UTF-8 smart-doc:torna-rest

// Apache Dubbo RPC文檔
// Generate html
mvn -Dfile.encoding=UTF-8 smart-doc:rpc-html
// Generate markdown
mvn -Dfile.encoding=UTF-8 smart-doc:rpc-markdown
// Generate adoc
mvn -Dfile.encoding=UTF-8 smart-doc:rpc-adoc

// 生成dubbo接口文檔推送到torna
mvn -Dfile.encoding=UTF-8 smart-doc:torna-rpc

或者

smart-doc開箱使用
java restful smart-api openapi Dubbo api文檔
上一篇: 為什麼資料庫讀寫分離可以提高性能
下一篇: mysql s 什麼意思_資料庫 data semantics 什麼意思？

繼續閱讀