Java api文档自动生成工具smartdoc+torna，Evalon4J Java接口文档生成工具

4747 671 2022-08-27


下面是关于Java接口文档生成工具

首先，一般做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>


1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

本人配置

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


1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

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"

}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

因为我集成的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


1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

注意：

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


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>文件夹上传到服务器

1

2

3

4

5

6

7

8

9

修改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文档自动生成，这玩意，没有最好，只有试用自己就可以了

资料介绍

授权协议 MIT
开发语言 Groovy
操作系统 Windows
软件类型 开源软件
所属分类 开发工具、 程序文档工具

软件简介

Evalon4J 是一个 Java 接口文档生成工具，直接通过命令行使用，支持Spring-MVC，JAX-RS，Swagger 2.0 等多种框架注解。同时它是付费产品 RabiAPI 使用的底层框架，通过静态分析源代码，直接生成相对应的接口文档。

和大多数开源框架不同，Evalon4J 使用 JavaParser 直接分析源代码，不需要使用任何 Gradle 或者 Maven 插件，所以使用者不会遇到任何和插件有关的烦人问题，更不会有任何版本冲突。

功能特色

  • 纯命令行工具，与项目本身零耦合，使用方便

  • 纯静态分析，无需事先编译，构建项目，极速生成

  • 支持Java泛型，递归，继承等写法

  • 支持不同框架的混合使用

  • 完全支持标准Javadoc注释

  • 完全支持枚举类型

参数说明

  • -p，指定需要生成文档的Java项目根目录，文档默认会生成在项目文件夹内

  • -o，指定导出的文档格式，目前已支持 markdown

  • -c，指定 evalon4j.json 配置文件位置，通常用不着

配置文件

你可以在项目根目录下提供一份 evalon4j.json 配置文件，运行时会自动读取。

{ "name": "", // 项目名称 "author": "whitecoms0s_", // 项目维护者 "version": "1.0", // 文档版本，默认为1.0 "includedServices": [], // 需要导出的服务名称或全名，白名单 "excludedServices": [], // 需要过滤的服务名称或全名，黑名单 "dependencies": [], // 项目依赖的源码包路径列表，(规划中) "onlyHttpApi": false, // 仅导出HTTP接口 "onlyJavaApi": false, // 仅导出RPC接口 "locale": "zh", // en 或 zh，会覆盖系统语言设置，没有该字段默认使用系统语言设置 }
 

代码(2503)JAVA(2355)接口(5337)

以上就是小编为大家整理的Java接口文档生成工具


版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。

上一篇:程序员常用的API接口管理工具有哪些？API接口文档模板管理工具
下一篇:【Python】文件操作（Python文件操作方法）
相关文章

 发表评论

暂时没有评论，来抢沙发吧~