好用的文档工具👉smart-doc

好用的文档工具👉smart-doc

转载请注明出处https://www.cnblogs.com/funnyzpc/p/18932813

smart-doc不得不说是一款非常好用的文档工具,尤其是它几乎不与项目耦合的特性十分值得所有java开发人员日常使用它~

之前及现在用的

我从事开发以来,用过形形色色各式各样的文档工具,比如一开始的用

01. word或excel

这种文档十分依赖于开发人员同步维护,另外office与代码是两套东西,耗时耗力且很容易

由于疏忽忘记维护,导致版本版本不一致的问题~

02. showdoc

这东西看起来比较美观,非常适合外部人员接入之使用,当然缺点也很明显:

  • 公开文档安全及私密性就差很多
  • 也同样存在手动编写的问题,需要跟随代码同步维护
  • 使用范围比较窄,虽方便接入人员用,测试及开发自测仍旧比较麻烦
  • 导入导出似乎受限制,不知道现在有没改善😂

03. swagger

后来有了有了 swagger,一开始觉得这东西蛮不错的,主要体现在:

  • 不需要再写word或excel
  • 定义文档接口的方式更贴合传统编码的方式
  • 文档可生成在线网页doc的方式也可以通过跑代码生成adoc文件+asciidoctor工具生成单html文档,这非常利于文档分发

东西虽好,但是缺点也是十分明显的:

  • 代码耦合性太强了,swagger依赖必须与代码一起部署(包括生产)
  • 在线文档十分便捷,但是由于 swagger 可能的漏洞的存在,增加了系统风险的可能性(这个本人碰到过)
  • 能生成实用的``html文档,可似乎缺少了供测试使用的 jmeterpostman文档,测试人员依然需要手动构建测试接口
  • 特别需要注意的是swagger v2及之后似乎缺少了html文档的生成途径(文档工具不能越做越返祖啊...)😂
  • swagger 文档不论是在线的还是离线的文档 对于复杂的 json 需要逐级便利 (如果能平铺为一个table就好了) 😓

04. smart-doc

这个文档工具在目前我所经手的项目中广泛之使用,如图,需要的功能基本都有了🥰

smart-doc 有啥优点

  • 由于仅有 plugin 及一个json配置,无任何 ApiModelPropertyApiModelSchema 侵入性注解代码
  • 可以生成诸如 html(单文件需要先走adoc后转html)、openapipostmanjmeterword 等主流且前端用也可后端测试用之文档
  • 文档定义更简单,仅需有限的注解及 Jakarta 相关注解配合使用即可, 其他扩展文档见 smart-doc

如何使用

  • 在项目中添加 plugin 配置,这里仅以 maven 项目实例
xml 复制代码
<!--文档工具-->
<plugin>
  <groupId>com.ly.smart-doc</groupId>
  <artifactId>smart-doc-maven-plugin</artifactId>
  <version>3.1.0</version>
  <configuration>
    <!--配置文件位置-->
    <configFile>./src/main/resources/smart-doc.json</configFile>
    <!--<projectName>${application.name}</projectName>-->
    <!--<configFile>${application.name}</configFile>-->
  </configuration>
  <!--项目编译时执行生成html不需要可以去掉executions标签-->
  <executions>
    <execution>
      <!--打包的时候构建文档(install package)-->
      <phase>package</phase>
      <goals>
        <!--adoc文档,后续用asciidoc生成html单文档-->
        <goal>adoc</goal>
        <!--构建文档类型 -->
        <!--api只构建html文档-->
        <!--<goal>html</goal>-->
        <!--统一接口只构建adoc文档-->
        <!--<goal>rpc-adoc</goal>-->
      </goals>
    </execution>
  </executions>
</plugin>

<!--文档工具:用于将smart-doc生成的adoc文件转换为html文档-->
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.8</version>
<configuration>
  <!--预构建文档目录-->
  <sourceDirectory>./adoc</sourceDirectory>
  <!--文档输出目录-->
  <outputDirectory>./doc</outputDirectory>
  <headerFooter>true</headerFooter>
  <doctype>book</doctype>
  <backend>html</backend>
  <sourceHighlighter>coderay</sourceHighlighter>
  <attributes>
    <!--菜单栏在左边-->
    <toc>left</toc>
    <!--多标题排列-->
    <toclevels>3</toclevels>
    <!--自动打数字序号-->
    <sectnums>true</sectnums>
  </attributes>
</configuration>
<executions>
  <execution>
    <phase>package</phase>
    <goals>
      <goal>process-asciidoc</goal>
    </goals>
  </execution>
</executions>
</plugin>
<!-- 文档工具结束-->

plugin在多模块项目中表现为:

  • 在项目中定义 smart-doc.json 配置文件,一般在 resources 目录下
json 复制代码
  {
    "outPath":"adoc",
    "allInOne":true,
    "allInOneDocFileName":"mee_admin-1.0.1",
    "projectName":"mee_admin",
    "createDebugPage":true,
    "revisionLogs":[
      {
        "version":"2025-06-26",
        "author":"shadow",
        "revisionTime":"2025-06-26 19:28:18",
        "status":"1.0.1",
        "remarks":"接口及文档优化"
      }
    ]
  }

这个 smart-doc.jsonplugin 中有引用,相对地址不要弄错了

  • ideamaven 面板依次操作=>生成单html文档文件

使用技巧及注意事项

  • 字段的注释不可以含有竖杠(eg: | ), 可能造成文档出现偏移
java 复制代码
// eg: 
/**
* 菜单类型(1.目录 | 2.菜单 | 3.按钮)
*/
private Integer type;
  • 入口注释字段 @param 的值不可为空, 可导致无法生成文档
java 复制代码
   // eg:
    /**
     * 系统::文件管理::删除
     * @param status 状态
     * @param
     */
    @RequiresPermissions("sys:sys_file:delete")
    @DeleteMapping("/delete")
    @ResponseBody
    public MeeResult<Integer> deleteById(@RequestParam(required = true) String id,@RequestParam(required = true) String status){
      return sysFileService.deleteById(id,status);
    }
  • smart-doc 强烈推荐使用 3.1.x 以上的版本,若使用 3.1.x 以下版本 多个 @RequestHeader 时生成的文档会出现行偏移
java 复制代码
  // eg:
  @RequiresPermissions("sys:sys_file:delete")
  @DeleteMapping("/delete")
  @ResponseBody
  public MeeResult<Integer> deleteById(@RequestHeader String aa ,@RequestHeader String status){
      return sysFileService.deleteById(id,status);
  }
  • 一定要注意xml配置的目录或文件的位置

  • 生成的jmeter文档不可避免的会出现打不开的问题,一般来是注释含有

    或者 数字或布尔默认值问题,此类问题建议按提示的行数 修改 jmx 内对应的行即可

  • 具体配置参见smart-doc官方文档

文档生成效果

  • html 文档

  • jmeter 文档

  • word 文档

相关推荐
钢铁男儿1 分钟前
C# 委托(调用带引用参数的委托)
java·mysql·c#
Apex Predator7 分钟前
windows安装maven环境
java·maven
Bug退退退12316 分钟前
RabbitMQ 工作模式
java·分布式·rabbitmq
小莫分享2 小时前
github 镜像节点
java
链上Sniper2 小时前
智能合约状态快照技术:实现 EVM 状态的快速同步与回滚
java·大数据·linux·运维·web3·区块链·智能合约
缘来是庄2 小时前
设计模式之建造者模式
java·设计模式·建造者模式
小湘西2 小时前
Apache HttpClient 的请求模型和 I/O 类型
java·http·apache
沃夫上校3 小时前
Feign调Post接口异常:Incomplete output stream
java·后端·微服务
q567315233 小时前
Java Selenium反爬虫技术方案
java·爬虫·selenium
张小洛3 小时前
Spring IOC容器核心阶段解密:★Bean实例化全流程深度剖析★
java·后端·spring·ioc容器·bean实例化