零侵入!试试这款Api接口文档生成器!

大家好,我是 Java陈序员

作为一名合格的程序员,不仅代码要写好,而且文档要写好。

虽然目前有成熟的框架可以快速生成接口文档,如大名鼎鼎的 Swagger.但是 Swagger 需要编写大量的注解来辅助生成文档,侵入了业务代码。不符合高内聚、低耦合的编程规范!

今天,给大家介绍一款零侵入的 Api 接口文档生成工具!

关注微信公众号:【Java陈序员】,获取开源项目分享、AI副业分享、超200本经典计算机电子书籍等。

项目介绍

smart-doc 是一款同时支持 JAVA REST API 和 Apache Dubbo RPC 接口文档生成的工具。完全基于注释生成文档,做到零侵入。

smart-doc 最大的优点就在于零侵入,不采用任何注解侵入到业务代码中

只需要按照 java-doc 标准编写注释,smart-doc 就能帮你生成一个简易明了的文档。

smart-doc 生成的文档支持 Markdown、Postman Collection2.0+、HTML5、OpenAPI 3.0+.

功能特性

此外,smart-doc 还支持自动推送文档到 Torna 企业级接口文档管理平台。

快速开始

1、新建 JSON 配置文件

在项目启动类所在模块的 resources 目录下创建 smart-doc.json 文件:

{
    "outPath": "/path/to/userdir"
}

outPath 指定文档输出的目录位置,也可以使用相对路径, 如: ./src/main/resources/static/doc

2、引入 Maven 插件依赖

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

如果是 Gradle 项目,同样的也需要引入插件:

plugins {
  id "com.ly.smart-doc" version "[最新版本]"
}

Gradle 项目完整配置可参考:

https://smart-doc-group.github.io/#/zh-cn/plugins/gradle

3、使用

在 IDEA 中直接使用 Maven 插件目录下的 smart-doc 模块

smart-doc 模块

或者使用如下命令输出接口文档:

mvn -Dfile.encoding=UTF-8 smart-doc:html
mvn -Dfile.encoding=UTF-8 smart-doc:markdown
mvn -Dfile.encoding=UTF-8 smart-doc:torna-rest

成功输出

总结

不管是新项目,还是老项目,smart-doc 都完美适用。对于新项目不需要再引入其他框架和编写代码;老项目只要完善 java-doc 标准的注释,就可以快速生成接口文档,完全不影响到业务代码!

下次如果要编写接口接口文档,可以试试使用 smart-doc 一键生成~

当然了,smart-doc 也存在缺点,就是文档不是在线的,不利于分享

针对于这一点,也有对应的解决方案,就是与企业级别的接口文档管理系统 Torna 结合。

最后,贴上项目地址:

https://github.com/TongchengOpenSource/smart-doc

最后

推荐的开源项目已经收录到 GitHub 项目,欢迎 Star

https://github.com/chenyl8848/great-open-source-project

或者访问网站,进行在线浏览:

https://chencoding.top:8090/#/

大家的点赞、收藏和评论都是对作者的支持,如文章对你有帮助还请点赞转发支持下,谢谢!

posted @ 2024-02-01 09:24  Java陈序员  阅读(234)  评论(0编辑  收藏  举报