好用的文檔工具👉smart-doc

好用的文檔工具??smart-doc

轉(zhuǎn)載請注明出處http://www.rzrgm.cn/funnyzpc/p/18932813

smart-doc不得不說是一款非常好用的文檔工具，尤其是它幾乎不與項目耦合的特性十分值得所有java開發(fā)人員日常使用它~

之前及現(xiàn)在用的

我從事開發(fā)以來，用過形形色色各式各樣的文檔工具,比如一開始的用

01. word或excel

這種文檔十分依賴于開發(fā)人員同步維護，另外office與代碼是兩套東西，耗時耗力且很容易
由于疏忽忘記維護，導(dǎo)致版本版本不一致的問題~

02. showdoc

這東西看起來比較美觀,非常適合外部人員接入之使用，當然缺點也很明顯：

公開文檔安全及私密性就差很多
也同樣存在手動編寫的問題，需要跟隨代碼同步維護
使用范圍比較窄，雖方便接入人員用，測試及開發(fā)自測仍舊比較麻煩
導(dǎo)入導(dǎo)出似乎受限制，不知道現(xiàn)在有沒改善??

03. swagger

后來有了有了 swagger,一開始覺得這東西蠻不錯的，主要體現(xiàn)在：

不需要再寫word或excel
定義文檔接口的方式更貼合傳統(tǒng)編碼的方式
文檔可生成在線網(wǎng)頁doc的方式也可以通過跑代碼生成adoc文件+asciidoctor工具生成單html文檔，這非常利于文檔分發(fā)

東西雖好，但是缺點也是十分明顯的：

代碼耦合性太強了，swagger依賴必須與代碼一起部署（包括生產(chǎn)）
在線文檔十分便捷，但是由于 swagger 可能的漏洞的存在，增加了系統(tǒng)風險的可能性（這個本人碰到過）
能生成實用的``html文檔，可似乎缺少了供測試使用的 jmeter 及 postman文檔，測試人員依然需要手動構(gòu)建測試接口
特別需要注意的是swagger v2及之后似乎缺少了html文檔的生成途徑（文檔工具不能越做越返祖啊...）??
swagger 文檔不論是在線的還是離線的文檔對于復(fù)雜的 json 需要逐級便利 (如果能平鋪為一個table就好了) ??

04. smart-doc

這個文檔工具在目前我所經(jīng)手的項目中廣泛之使用，如圖，需要的功能基本都有了??

smart-doc 有啥優(yōu)點

由于僅有 plugin 及一個json配置,無任何 ApiModelProperty 、 ApiModel 及 Schema 侵入性注解代碼
可以生成諸如 html（單文件需要先走adoc后轉(zhuǎn)html）、openapi、postman、jmeter、word 等主流且前端用也可后端測試用之文檔
文檔定義更簡單，僅需有限的注解及 Jakarta 相關(guān)注解配合使用即可, 其他擴展文檔見 smart-doc

如何使用

在項目中添加 plugin 配置，這里僅以 maven 項目實例

<!--文檔工具-->
<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>
  <!--項目編譯時執(zhí)行生成html不需要可以去掉executions標簽-->
  <executions>
    <execution>
      <!--打包的時候構(gòu)建文檔(install package)-->
      <phase>package</phase>
      <goals>
        <!--adoc文檔，后續(xù)用asciidoc生成html單文檔-->
        <goal>adoc</goal>
        <!--構(gòu)建文檔類型 -->
        <!--api只構(gòu)建html文檔-->
        <!--<goal>html</goal>-->
        <!--統(tǒng)一接口只構(gòu)建adoc文檔-->
        <!--<goal>rpc-adoc</goal>-->
      </goals>
    </execution>
  </executions>
</plugin>

<!--文檔工具:用于將smart-doc生成的adoc文件轉(zhuǎn)換為html文檔-->
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.8</version>
<configuration>
  <!--預(yù)構(gòu)建文檔目錄-->
  <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>
    <!--自動打數(shù)字序號-->
    <sectnums>true</sectnums>
  </attributes>
</configuration>
<executions>
  <execution>
    <phase>package</phase>
    <goals>
      <goal>process-asciidoc</goal>
    </goals>
  </execution>
</executions>
</plugin>
<!-- 文檔工具結(jié)束-->

plugin在多模塊項目中表現(xiàn)為:

在項目中定義 smart-doc.json 配置文件,一般在 resources 目錄下

  {
    "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":"接口及文檔優(yōu)化"
      }
    ]
  }

這個 smart-doc.json 在 plugin 中有引用，相對地址不要弄錯了

在 idea 的 maven 面板依次操作=>生成單html文檔文件

使用技巧及注意事項

字段的注釋不可以含有豎杠(eg: | ), 可能造成文檔出現(xiàn)偏移

// eg: 
/**
* 菜單類型(1.目錄 | 2.菜單 | 3.按鈕）
*/
private Integer type;

入口注釋字段 @param 的值不可為空, 可導(dǎo)致無法生成文檔

   // eg:
    /**
     * 系統(tǒng)::文件管理::刪除
     * @param status 狀態(tài)
     * @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 時生成的文檔會出現(xiàn)行偏移

  // eg:
  @RequiresPermissions("sys:sys_file:delete")
  @DeleteMapping("/delete")
  @ResponseBody
  public MeeResult<Integer> deleteById(@RequestHeader String aa ,@RequestHeader String status){
      return sysFileService.deleteById(id,status);
  }