Java api文档自动生成工具smartdoc+torna

首先，一般做java服务端都用过postman，并且都写过前端调用的api文档接口，并且也用过市面上的一些工具。
API自文档动生成，能够省去了写文档的时间。
当然，当前也会有很多类似的开源工具，我们先看几种对比下。

api 文档写作对比

为什么写这几个，因为涉及到API文档的演变
1、传统的word文档
内部使用，使用word固定格式，写麻烦，共享更麻烦
2、showdoc
增加了api文档的统一格式，写变简单的，共享变简单了
3、swagger
增加了java代码注释，自动生成API文档，基本上不用怎么写了，共享更方便了，但是swagger有一个大问题，侵入性太强
4、smartdoc+torna
现在比较主流的使用
标准注释+支持多平台+测试功能

smartdoc

官网：https://gitee.com/smart-doc-team
smartdoc wiki：https://gitee.com/smart-doc-team/smart-doc/wikis/HOME?sort_id=3127893

介绍

smart-doc开源API文档生成工具官方组织。官方致力为java web开发者提供一款不将就的API文档生成工具。官方当前的开源产品为smart-doc、smart-doc-maven-plugin、smart-doc-gradle-plugin。

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

功能

零注解、零学习成本、只需要写标准JAVA注释。
基于源代码接口定义自动推导，强大的返回结构推导。
支持Spring MVC、Spring Boot、Spring Boot Web Flux(controller书写方式)、Feign。
支持Callable、Future、CompletableFuture等异步接口返回的推导。
支持JavaBean上的JSR303参数校验规范，包括分组验证。
对JSON请求参数的接口能够自动生成模拟JSON参数。
对一些常用字段定义能够生成有效的模拟值。
支持生成JSON返回值示例。
支持从项目外部加载源代码来生成字段注释(包括标准规范发布的jar包)。
支持生成多种格式文档：Markdown、HTML5、Asciidoctor、Postman Collection、OpenAPI 3.0。 Up- 开放文档数据，可自由实现接入文档管理系统。
支持导出错误码和定义在代码中的各种字典码到接口文档。
支持Maven、Gradle插件式轻松集成。
支持Apache Dubbo RPC接口文档生成。
debug接口调试html5页面完全支持文件上传，下载(@download tag标记下载方法)测试。

Maven Plugin

<plugin>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>[最新版本]</version>
    <configuration>
        <!--指定生成文档的使用的配置文件,配置文件放在自己的项目中-->
        <configFile>./src/main/resources/smart-doc.json</configFile>
        <!--指定项目名称-->
        <projectName>测试</projectName>
        <!--smart-doc实现自动分析依赖树加载第三方依赖的源码，如果一些框架依赖库加载不到导致报错，这时请使用excludes排除掉-->
        <excludes>
            <!--格式为：groupId:artifactId;参考如下-->
            <exclude>com.alibaba:fastjson</exclude>
        </excludes>
        <!--自1.0.8版本开始，插件提供includes支持,配置了includes后插件会按照用户配置加载而不是自动加载，因此使用时需要注意-->
        <!--smart-doc能自动分析依赖树加载所有依赖源码，原则上会影响文档构建效率，因此你可以使用includes来让插件加载你配置的组件-->
        <includes>
            <!--格式为：groupId:artifactId;参考如下-->
            <!--也可以支持正则式如：com.alibaba:.* -->
            <include>com.alibaba:fastjson</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>

本人配置

<build>
        <plugins>
            <plugin>
                <groupId>com.github.shalousun</groupId>
                <artifactId>smart-doc-maven-plugin</artifactId>
                <version>2.2.3</version>
                <configuration>
                    <configFile>./src/main/resources/smart-doc.json</configFile>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

smart-doc.json

官方的配置说明见：https://gitee.com/smart-doc-team/smart-doc
本人的测试配置：

{
  "serverUrl": "http://127.0.0.1",
  "isStrict": false,
  "allInOne": true,
  "packageFilters": "com.xy.saas.consumer.controller.*",
  "projectName": "测试项目",
  "appKey": "20210811875071685840076800",
  "appToken": "7b65406490ea48babedf52f73eddaa19",
  "secret": "f#T0Qotd#<$O%hcsAmAn5uBAx!ZH.>^.",
  "openUrl": "http://localhost:7700/api",
  "debugEnvName":"测试环境",
  "debugEnvUrl":"http://127.0.0.1",
  "outPath":"doc"
}

因为我集成的torna，所以，具体的配置看官方提供的说明
注意⚠️：
1、packageFilters配置的包名后一定要加".*"
2、outPath一定要配置

maven startdoc执行

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

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

注意：
生成的时候，可能会报错，或者包找不到等等，多执行两次试试。

torna

先上官网，一般看官方网站就够用了，http://torna.cn

能干什么？

官网一张图说的很明白

推荐组合

smart-doc + Torna实现文档全流程自动化

如果您使用Java语言，推荐使用smart-doc + Torna

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

通过这套组合您可以实现：只需要写完Java注释就能把接口信息推送到Torna平台，从而实现接口预览、接口调试。

推送的内容有：接口名称/author/Path参数/Header/请求参数/返回参数/字典列表/公共错误码

如果您是非Java语言，可以使用表单页面编辑以上内容，完成后同样可以进行接口预览、调试。

环境准备

Java8，Torna要求Java版本最低为Java8
Maven3，包管理以及构建工具，最低版本要求maven3
nodejs12，前端开发需要安装nodejs，建议版本12，版本太高可能会有问题
Mysql5.7(推荐)

项目准备

下载发行版本：https://gitee.com/durcframework/torna/tags
mysql初始化，见文档

部署

开发完成后，需要对项目进行打包发布，步骤如下：

如果您的开发环境为macOS/Linux系统，执行sh build.sh，如果是Windows系统双击执行build.bat

构建结果在dist/torna-目录，最终结构如下：

torna-<version>                 # 根目录
├── application.properties      # 配置文件
├── dist                        # 前端资源
├── debug.sh                    # 线上调试
├── shutdown.sh                 # 结束服务脚本
├── startup.bat                 # 启动服务脚本（windows）
├── startup.sh                  # 启动服务脚本（macOS/Linux）
└── torna.jar                   # 服务程序
把torna-<version>文件夹上传到服务器

修改application.properties配置文件内容，改为线上配置

执行startup.sh，启动应用（Windows执行startup.bat）

访问：http://ip:7700

账号：可以见mysql初始化中的数据(admin@torna.cn)，密码默认在配置文件中：123456

验证

smartdoc执行tarna推送

编译推送

推送完成

浏览器查看下-管理模式

浏览器查看下-浏览模式

浏览器查看下-接口调用
功能类似简版的postman，一看就会了。。

结束

官方地址：
smartdoc
官网：https://gitee.com/smart-doc-team
smartdoc wiki：https://gitee.com/smart-doc-team/smart-doc/wikis/HOME?sort_id=3127893
torna
http://torna.cn

当前，还有其他一些比较好的api文档自动生成，这玩意，没有最好，只有试用自己就可以了