快捷導(dǎo)航

spring?boot集成smart-doc自動生成接口文檔詳解

更新時間：2022年09月23日 16:19:01 作者：紅姐最牛

這篇文章主要介紹了spring?boot集成smart-doc自動生成接口文檔詳解，smart-doc是一款同時支持java?restful?api和Apache?Dubbo?rpc接口文檔生成的工具，smart-doc顛覆了傳統(tǒng)類似swagger這種大量采用注解侵入來生成文檔的實現(xiàn)方法

前言

smart-doc 是一款同時支持 java restful api 和 Apache Dubbo rpc 接口文檔生成的工具，smart-doc 顛覆了傳統(tǒng)類似 swagger 這種大量采用注解侵入來生成文檔的實現(xiàn)方法。

smart-doc 完全基于接口源碼分析來生成接口文檔，完全做到零注解侵入，你只需要按照 java 標(biāo)準(zhǔn)注釋編寫，smart-doc 就能幫你生成一個簡易明了的 markdown 或是一個像 GitBook 樣式的靜態(tài) html 文檔。如果你已經(jīng)厭倦了 swagger 等文檔工具的無數(shù)注解和強(qiáng)侵入污染，那請擁抱 smart-doc 吧！

功能特性

支持接口 debug。
零注解、零學(xué)習(xí)成本、只需要寫標(biāo)準(zhǔn) java 注釋。
基于源代碼接口定義自動推導(dǎo)，強(qiáng)大的返回結(jié)構(gòu)推導(dǎo)。
支持 Spring MVC,Spring Boot,Spring Boot Web Flux (controller 書寫方式),JAX-RS 規(guī)范。
支持 Callable,Future,CompletableFuture 等異步接口返回的推導(dǎo)。
支持 JavaBean 上的 JSR303 參數(shù)校驗規(guī)范，支持分組驗證。
對 json 請求參數(shù)的接口能夠自動生成模擬 json 參數(shù)。
對一些常用字段定義能夠生成有效的模擬值。
支持生成 json 返回值示例。
支持從項目外部加載源代碼來生成字段注釋 (包括標(biāo)準(zhǔn)規(guī)范發(fā)布的 jar 包)。
支持生成多種格式文檔：Markdown、HTML5、Asciidoctor、Postman collection、Open Api 3.0+。
輕易實現(xiàn)在 Spring Boot 服務(wù)上在線查看靜態(tài) HTML5 api 文檔。
開放文檔數(shù)據(jù)，可自由實現(xiàn)接入文檔管理系統(tǒng)。
一款代碼注釋檢測工具，不寫注釋的小伙伴逃不過法眼了。
插件式快速集成 (支持 maven 和 gradle 插件)。
支持 Apache Dubbo rpc 文檔生成。
支持國產(chǎn) Solon 應(yīng)用開發(fā)框架。

smart-doc官網(wǎng)地址：Document

1 項目中創(chuàng)建 /src/main/resources/smart-doc.json配置文件

2 配置內(nèi)容如下（指定文檔的輸出路徑）

{
  "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實現(xiàn)自動分析依賴樹加載第三方依賴的源碼，如果一些框架依賴庫 
                         加載不到導(dǎo)致報錯，這時請使用excludes排除掉-->
                    <excludes>
                        <!--格式為：groupId:artifactId;參考如下-->
                        <!--也可以支持正則式如：com.alibaba:.* -->
                        <exclude>com.alibaba:fastjson</exclude>
                    </excludes>
                    <!--includes配置用于配置加載外部依賴源碼,配置后插件會按照配置項加載外部 
                       源代碼而不是自動加載所有，因此使用時需要注意-->
                    <!--smart-doc能自動分析依賴樹加載所有依賴源碼，原則上會影響文檔構(gòu)建效 
                       率，因此你可以使用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>
                        <!--如果不需要在執(zhí)行編譯時啟動smart-doc，則將phase注釋掉-->
                        <phase>compile</phase>
                        <goals>
                            <!--smart-doc提供了html、openapi、markdown等goal，可按需配置-->
                            <goal>html</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>