快捷導(dǎo)航

spring?boot集成smart-doc自動(dòng)生成接口文檔詳解

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

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

前言

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

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

功能特性

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

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

1 項(xiàng)目中創(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>
                    <!--指定生成文檔的使用的配置文件,配置文件放在自己的項(xiàng)目中-->
                    <configFile>./src/main/resources/smart-doc.json</configFile>
                    <!--指定項(xiàng)目名稱-->
                    <projectName>測(cè)試</projectName>
                    <!--smart-doc實(shí)現(xiàn)自動(dòng)分析依賴樹(shù)加載第三方依賴的源碼，如果一些框架依賴庫(kù) 
                         加載不到導(dǎo)致報(bào)錯(cuò)，這時(shí)請(qǐng)使用excludes排除掉-->
                    <excludes>
                        <!--格式為：groupId:artifactId;參考如下-->
                        <!--也可以支持正則式如：com.alibaba:.* -->
                        <exclude>com.alibaba:fastjson</exclude>
                    </excludes>
                    <!--includes配置用于配置加載外部依賴源碼,配置后插件會(huì)按照配置項(xiàng)加載外部 
                       源代碼而不是自動(dòng)加載所有，因此使用時(shí)需要注意-->
                    <!--smart-doc能自動(dòng)分析依賴樹(shù)加載所有依賴源碼，原則上會(huì)影響文檔構(gòu)建效 
                       率，因此你可以使用includes來(lái)讓插件加載你配置的組件-->
                    <includes>
                        <!--格式為：groupId:artifactId;參考如下-->
                        <!--也可以支持正則式如：com.alibaba:.* -->
                        <include>com.alibaba:fastjson</include>
                        <!-- 如果配置了includes的情況下， 使用了mybatis-plus的分頁(yè)需要 
                             include所使用的源碼包 -->
                        <include>com.baomidou:mybatis-plus-extension</include>
                        <!-- 如果配置了includes的情況下， 使用了jpa的分頁(yè)需要include所使用 
                             的源碼包 -->
                        <include>org.springframework.data:spring-data-commons</include>
                    </includes>
                </configuration>
                <executions>
                    <execution>
                        <!--如果不需要在執(zhí)行編譯時(shí)啟動(dòng)smart-doc，則將phase注釋掉-->
                        <phase>compile</phase>
                        <goals>
                            <!--smart-doc提供了html、openapi、markdown等goal，可按需配置-->
                            <goal>html</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

4 運(yùn)行插件

5 找到存放路徑瀏覽器打開(kāi)

6 測(cè)試結(jié)果

到此這篇關(guān)于spring boot集成smart-doc自動(dòng)生成接口文檔詳解的文章就介紹到這了,更多相關(guān)spring boot集成smart-doc 內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

您可能感興趣的文章: