Smart-Doc

简体中文

English

简体中文

English

主题

Maven ​

从smart-doc 1.7.9开始官方提供了Maven插件，可以在项目中通过运行插件来直接生成文档。

环境要求 ​

  • Maven 3.8+
  • JDK1.8+

插件使用范围 ​

在smart-doc-maven-plugin 1.0.2以前的版本，在多模块的Maven项目中使用插件存在着各种问题。

自smart-doc-maven-plugin 1.0.2插件开始，我们在插件上做了很多努力，不仅解决了插件在Maven多模块中存在的各种问题， 而且为smart-doc带来更强的源码加载能力。 在使用插件的情况下，smart-doc的文档分析能力增强的很多。

smart-doc-maven-plugin 1.0.8开始支持Dubbo RPC文档生成。

也建议使用旧版本smart-doc-maven-plugin的用户立即升级到最新版本。后续在使用smart-doc时推荐采用插件的方式。

使用插件后就不需要在项目的maven dependencies中添加smart-doc的依赖了，直接使用插件即可。如果需要保留原有单元测试，需要引用smart-doc的依赖。

使用参考如下：

添加插件 ​

xml
<plugin>
    <groupId>com.ly.smart-doc</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>[最新版本]</version>
    <configuration> 
        <configFile>./src/main/resources/smart-doc.json</configFile>  
        <projectName>${project.description}</projectName>  
        <includes>  
            <!-- 使用了mybatis-plus的Page分页需要include所使用的源码包 -->
            <include>com.baomidou:mybatis-plus-extension</include>
            <!-- 使用了mybatis-plus的IPage分页需要include mybatis-plus-core-->
            <include>com.baomidou:mybatis-plus-core</include>
            <!-- 使用了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>

插件 configuration ​

configFile ​

指定生成文档的使用的配置文件。相对路径时请用./开头，eg: ./src/main/resources/smart-doc.json。 如果你通过mvn命令来使用插件，那么你也可以通过在命令行中使用-DconfigFile参数来指定, 例如：

shell
mvn -Dfile.encoding=UTF-8  -DconfigFile="src/main/resources/smart-doc.json"  smart-doc:html

注意： pom.xml中smart-doc插件的configFile配置优先级高于命令行，如果要使用命令指定configFile， 那么请删除pom.xml中的configFile配置。

projectName ​

指定项目名称，推荐使用动态参数，例如${project.description}。

2.3.4开始, 如果smart-doc.json中和此处都未设置projectName，插件自动设置为pom中的projectName

excludes & includes ​

加载源码机制 ​

smart-doc会自动分析依赖树加载所有依赖源码，不过这样会存在两个问题：

  • 加载不需要的源码，影响文档构建效率
  • 某些不需要的依赖加载不到时，会报错（smart-doc默认所有的依赖都是必须的）
依赖匹配规则 ​
  • 匹配单个依赖： groupId:artifactId
  • 正则匹配多个依赖： groupId:.*
includes ​

使用includes，按需加载依赖，减少不必要的依赖解析。

注意： 如果配置了includes, 插件只会加载includes中指定的依赖。不再按照pom中的依赖解析来加载。

通常我们需要的依赖就除了几个常见的三方库，就是公司内部的二方库，和项目中的其他模块。

xml
<includes>
    <!-- 使用了mybatis-plus的Page分页需要include所使用的源码包 -->
    <include>com.baomidou:mybatis-plus-extension</include>
    <!-- 使用了mybatis-plus的IPage分页需要include mybatis-plus-core-->
    <include>com.baomidou:mybatis-plus-core</include>
    <!-- 使用了jpa的分页需要include所使用的源码包 -->
    <include>org.springframework.data:spring-data-commons</include>
</includes>
xml
<includes>
      <!--加载groupId为com.xxx的所有依赖-->
      <include>com.xxx:.*</include>
</includes>
excludes ​

在运行插件时，遇到某些Class无法加载的情况，将该Class所在的依赖排除。

xml
<excludes>
     <!--排除mongodb依赖-->
     <exclude>org.springframework.boot:spring-boot-mongodb</exclude>
</excludes>
excludes & includes 最佳实践 ​

  1. 要使用include，加载需要的源码，如果不需要别的依赖，可以写项目自身的 groupId:artifactId

  2. 遇到报错后，使用excludes排除报错依赖

添加smart-doc生成文档的配置 ​

在项目中添加创建一个smart-doc.json配置文件，插件读取这个配置来生成项目的文档， 这个配置内容实际上就是以前采用单元测试编写的ApiConfig转成json后的结果，因此关于配置项说明可以参考原来单元测试的配置。

最小配置单元：

{
   "outPath": "D://md2" //指定文档的输出路径
}

详细配置请参考具体文档(定制化 | 配置项)

上面的json配置实例中只有"outPath"是必填项。其它的配置根据自身项目需要来配置。

注意： 对于老用户完全可以通过Fastjson或者是Gson库将ApiConfig转化成json配置。

运行插件生成文档 ​

5.1 使用maven命令行 ​

bash
//生成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
// 生成word格式文档，推荐使用smart-doc 3.0.2及更高版本
mvn -Dfile.encoding=UTF-8 smart-doc:word
// 生成jmeter性能压测脚本
mvn -Dfile.encoding=UTF-8 smart-doc:jmeter

// 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

// 标注 `@javadoc` 的普通接口或者静态工具类生成文档, 3.0.5版本开始支持
// Generate html
mvn -Dfile.encoding=UTF-8 smart-doc:javadoc-html
// Generate markdown
mvn -Dfile.encoding=UTF-8 smart-doc:javadoc-markdown
// Generate adoc
mvn -Dfile.encoding=UTF-8 smart-doc:javadoc-adoc

在使用mvn命令构建时如果想查看debug日志，debug日志也能够帮助你去分析smart-doc-maven插件的源码加载情况，可以加一个-X参数。例如：

shell
mvn -X -Dfile.encoding=UTF-8 smart-doc:html

注意： 尤其在window系统下，如果实际使用mvn命令行执行文档生成，可能会出现乱码，因此需要在执行时指定-Dfile.encoding=UTF-8。

查看maven的编码

bash
# mvn -version
Apache Maven 3.3.3 (7994120775791599e205a5524ec3e0dfe41d4a06; 2015-04-22T19:57:37+08:00)
Maven home: D:\ProgramFiles\maven\bin\..
Java version: 1.8.0_191, vendor: Oracle Corporation
Java home: D:\ProgramFiles\Java\jdk1.8.0_191\jre
Default locale: zh_CN, platform encoding: GBK
OS name: "windows 10", version: "10.0", arch: "amd64", family: "dos"

5.2 在IDEA中生成文档 ​

idea中smart-doc-maven插件使用

插件源码 ​

Gitee

GitHub

插件调试 ​

在使用smart-doc-maven-plugin插件来构建生成API文档的过程中可能会出现一些错误问题。 如果一些复杂问题出现时仅仅是粗略的将错误信息放在提到issue中， 官方并不能根据这些简单的错误信息来解决问题，因为用户的使用环境和所写的代码都是我们无法模拟的。 因此我们希望使用smart-doc-maven-plugin的用户在报错时能够通过debug来获取到更详细的信息。 在提issue时添加详细的问题描述，这样也能帮助我们更加快速的修改问题。 下面将介绍如何来调试smart-doc-maven-plugin插件。

添加smart-doc依赖 ​

因为smart-doc-maven-plugin最终是使用smart-doc来完成项目的源码分析和文档生成的， 通常情况下真正的调试的代码是smart-doc。但这个过程主要通过smart-doc-maven-plugin来排查。

xml
<dependency>
     <groupId>com.ly.smart-doc</groupId>
     <artifactId>smart-doc</artifactId>
     <version>[最新版本]</version>
     <scope>test</scope>
</dependency>

注意： 使用smart-doc的版本最好和插件依赖的smart-doc版本一致。

添加断点 ​

添加断点如图所示 输入图片说明

Debug模式运行构建目标 ​

maven插件在idea中运行debug非常简单，操作如下图。 启动debug 这样就可以直接进入断点了。

提示： 上面是通过插件去作为入口调试smart-doc的源码，如果你想调试插件本身的源码执行过程，则将插件的依赖添加到项目依赖中,如下：

xml
<dependency>
    <groupId>com.ly.smart-doc</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>【maven仓库最新版本】</version>
</dependency>

然后通过上面 的类似步骤调试smart-doc-maven-plugin的源码

基于 MIT 许可发布

版权所有 © 2024-2024 smart-doc