spring boot整合smart-doc自動生成介面檔案詳解

2022-09-26 14:06:00

前言

smart-doc 是一款同時支援 java restful api 和 Apache Dubbo rpc 介面檔案生成的工具，smart-doc 顛覆了傳統類似 swagger 這種大量採用註解侵入來生成檔案的實現方法。

smart-doc 完全基於介面原始碼分析來生成介面檔案，完全做到零註解侵入，你只需要按照 java 標準註釋編寫，smart-doc 就能幫你生成一個簡易明瞭的 markdown 或是一個像 GitBook 樣式的靜態 html 檔案。如果你已經厭倦了 swagger 等檔案工具的無數註解和強侵入汙染，那請擁抱 smart-doc 吧！

功能特性

支援介面 debug。
零註解、零學習成本、只需要寫標準 java 註釋。
基於原始碼介面定義自動推導，強大的返回結構推導。
支援 Spring MVC,Spring Boot,Spring Boot Web Flux (controller 書寫方式),JAX-RS 規範。
支援 Callable,Future,CompletableFuture 等非同步介面返回的推導。
支援 JavaBean 上的 JSR303 引數校驗規範，支援分組驗證。
對 json 請求引數的介面能夠自動生成模擬 json 引數。
對一些常用欄位定義能夠生成有效的模擬值。
支援生成 json 返回值範例。
支援從專案外部載入原始碼來生成欄位註釋 (包括標準規範釋出的 jar 包)。
支援生成多種格式檔案：Markdown、HTML5、Asciidoctor、Postman collection、Open Api 3.0+。
輕易實現在 Spring Boot 服務上線上檢視靜態 HTML5 api 檔案。
開放檔案資料，可自由實現接入檔案管理系統。
一款程式碼註釋檢測工具，不寫註釋的小夥伴逃不過法眼了。
外掛式快速整合 (支援 maven 和 gradle 外掛)。
支援 Apache Dubbo rpc 檔案生成。
支援國產 Solon 應用開發框架。

smart-doc官網地址：Document

1 專案中建立 /src/main/resources/smart-doc.json組態檔

2 設定內容如下（指定檔案的輸出路徑）

{
  "outPath": "D://md2"
}

3 pom.xml下新增設定

            <plugin>
                <groupId>com.github.shalousun</groupId>
                <artifactId>smart-doc-maven-plugin</artifactId>
                <version>2.1.0</version>
                <configuration>
                    <!--指定生成檔案的使用的組態檔,組態檔放在自己的專案中-->
                    <configFile>./src/main/resources/smart-doc.json</configFile>
                    <!--指定專案名稱-->
                    <projectName>測試</projectName>
                    <!--smart-doc實現自動分析依賴樹載入第三方依賴的原始碼，如果一些框架依賴庫 
                         載入不到導致報錯，這時請使用excludes排除掉-->
                    <excludes>
                        <!--格式為：groupId:artifactId;參考如下-->
                        <!--也可以支援正則式如：com.alibaba:.* -->
                        <exclude>com.alibaba:fastjson</exclude>
                    </excludes>
                    <!--includes設定用於設定載入外部依賴原始碼,設定後外掛會按照設定項載入外部 
                       原始碼而不是自動載入所有，因此使用時需要注意-->
                    <!--smart-doc能自動分析依賴樹載入所有依賴原始碼，原則上會影響檔案構建效 
                       率，因此你可以使用includes來讓外掛載入你設定的元件-->
                    <includes>
                        <!--格式為：groupId:artifactId;參考如下-->
                        <!--也可以支援正則式如：com.alibaba:.* -->
                        <include>com.alibaba:fastjson</include>
                        <!-- 如果設定了includes的情況下， 使用了mybatis-plus的分頁需要 
                             include所使用的原始碼包 -->
                        <include>com.baomidou:mybatis-plus-extension</include>
                        <!-- 如果設定了includes的情況下， 使用了jpa的分頁需要include所使用 
                             的原始碼包 -->
                        <include>org.springframework.data:spring-data-commons</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>