# smart-doc

smart-doc[smɑːt dɒk]是一款同时支持JAVA REST API和JAVA WebSocket和Apache Dubbo RPC接口文档生成的工具，smart-doc在业内率先提出基于JAVA泛型定义推导的理念，完全基于接口源码来分析生成接口文档，不采用任何注解侵入到业务代码中。你只需要按照Javadoc标准编写注释， smart-doc就能帮你生成一个简易明了的Markdown、HTML5、Postman Collection2.0+、OpenAPI 3.0+的文档。

smart-doc (opens new window) + Torna 组成行业领先的文档生成和管理解决方案，使用smart-doc无侵入完成Java源代码分析和提取注释生成API文档，自动将文档推送到Torna企业级接口文档管理平台。

比如有一个接口定义如下：


/**
 * 产品模块
 *
 * @author thc
 */
@RestController
@RequestMapping("shop/product")
public class ProductController {

    /**
     * 查询产品
     *
     * @param productNo 产品id|123
     * @return
     */
    @GetMapping
    public Result<ProductVO> get(@RequestParam Integer productNo) {
        ProductVO productVO = new ProductVO();
        productVO.setProductNo(String.valueOf(productNo));
        return Result.ok(productVO);
    }

}

ProductVO类：

public class ProductVO {
    /**
     * 产品id
     *
     * @mock aa
     */
    private String productNo;

    /**
     * 备注
     *
     * @mock xxx
     */
    private String remark;

    /**
     * 产品详情
     *
     * @mock
     */
    private ProductDetailVO productDetailVO;
    
    ... 省略getter setter   
}

然后通过一条推送命令即可把文档信息推送到Torna平台，前往Torna平台预览效果如下图所示：

# 整合smart-doc

示例工程 (opens new window)

下面通过一个springboot工程讲解如何整合smart-doc

在Torna中新建一个项目，进入项目创建一个模块，输入模块名称

点击OpenAPI，可以看到请求接口和token

到此Torna这边配置完毕

创建一个springboot工程，然后改成多模块形式，最终得到如下目录结构：

torna-and-smart-doc  # 项目根目录 
├──shop-common       # 公共模块
├──shop-web          # 接口模块(springboot启动模块)
├──pom.xml           # 根pom文件
└──readme.md

在项目根pom.xml中添加smart-doc插件

<plugins>
    <!-- smart-doc插件 -->
    <plugin>
        <groupId>com.ly.smart-doc</groupId>
        <artifactId>smart-doc-maven-plugin</artifactId>
        <version>3.0.2</version>
        <configuration>
            <!--指定生成文档的使用的配置文件-->
            <configFile>${basedir}/src/main/resources/smart-doc.json</configFile>
            <!--指定项目名称-->
            <projectName>商城项目</projectName>
        </configuration>
        <executions>
            <execution>
                <phase>package</phase>
            </execution>
        </executions>
    </plugin>
</plugins>

在shop-web中的resources下添加一个smart-doc.json文件，内容如下：

{
  "outPath": "target/doc",
  "projectName": "商城项目",
  "packageFilters": "cn.torna.example.web.controller.*",
  "openUrl": "http://localhost:7700/api",
  "appToken": "7d58c03fee554abc929b4cb2ad76feeb",
  "debugEnvName":"本地环境",
  "debugEnvUrl":"http://127.0.0.1:8080",
  "tornaDebug": true,
  "replace": true
}

参数说明:

outPath：固定填这个不用变
projectName：项目名称
packageFilters：Controller接口对应的package目录，多个用,隔开
openUrl：Torna中的OpenAPI接口
appToken：Torna中的OpenAPI token
debugEnvName：Torna中调试环境名称
debugEnvUrl：Torna中调试环境地址
tornaDebug：是否开启调试，初次使用建议开始，后面稳定了关闭
replace：是否替换文档，建议true

对应关系如下图所示：

到此smart-doc配置完毕，接下来推送文档到Torna

在项目根目录输入maven命令：mvn -Dfile.encoding=UTF-8 smart-doc:torna-rest -pl :shop-web -am

其中-pl :shop-web -am表示推送哪个子模块

推送成功后前往Torna接口列表查看文档

# 常见问题

参数描述没有显示/依赖第三方jar没有描述信息？

smart-doc的原理是扫描源码文件，然后解析注释，因此必须确保有源码。

如果有些公共类放在第三方jar

确保第三方jar上传到maven私服连带源码一起上传

源码上传到maven方法：

第三方项目添加maven插件：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-source-plugin</artifactId>
    <version>3.2.1</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>jar-no-fork</goal>
            </goals>
        </execution>
    </executions>
</plugin>

执行mvn clean deploy -DskipTests上传jar并上传源码

然后再smart-doc插件中的<configuration>节点下新增如下配置

<!--includes配置用于配置加载外部依赖源码,配置后插件会按照配置项加载外部源代码而不是自动加载所有，因此使用时需要注意-->
<!--smart-doc能自动分析依赖树加载所有依赖源码，原则上会影响文档构建效率，因此你可以使用includes来让插件加载你配置的组件-->
<includes>
    <!--格式为：groupId:artifactId;参考如下-->
    <!--也可以支持正则式如：com.alibaba:.* -->
    <include>your groupId:your artifactId</include>
    <!-- 如果配置了includes的情况下， 使用了mybatis-plus的分页需要include所使用的源码包 -->
    <include>com.baomidou:mybatis-plus-extension</include>
    <!-- 如果配置了includes的情况下， 使用了jpa的分页需要include所使用的源码包 -->
    <include>org.springframework.data:spring-data-commons</include>
</includes>

← 启动参数多版本号管理 1.22.0 →