開源工具 — 一個極簡的Java RESTful API文檔工具smalldoc

---

項目

• https://github.com/liuhuagui/smalldoc 一個基於Java標準註釋的 RESTful API 文檔工具
• smalldoc-antd-react-ui（https://github.com/liuhuagui/smalldoc-antd-react-ui）

爲什麼要造輪子？

• 強迫症患者，接受不了Swagger的各式註解對代碼的入侵造成的冗雜，更渴望清潔的代碼；
• 註解的使用需要一定的學習成本；
• 隨後嘗試使用Apidoc，儘管Apidoc是基於註釋生成文檔，但是學習成本並沒有降低，你需要學習額外的註釋Tag，同時你不得不使用這些特殊的Tag將你所需接口的相關信息手動寫出來，感覺並沒有大幅度降低書寫文檔的工作量；
• 也有一些基於Java標準註釋生成文檔的項目，但是有的無法支持實體參數、泛型變量、多模塊依賴，有的Bug太多，UI界面不夠友好，使用方式過於複雜，甚至邏輯處理上存在問題。

特性

• 基於Java源碼、標準註釋以及Tag生成文檔，無代碼入侵，保證代碼整潔，同時保證開發人員的註釋習慣與註釋規範
• 提供了友好的默認UI
• 提供了文檔RESTEful API，支持實現自定義UI
• 提供規範配置方式，使用更方便
• 提供相應的spring-boot-starter，同時支持傳統spring與spring-boot
• 支持關聯實體參數
• 支持泛型
• 支持忽略某個參數
• 支持忽略解析指定包或指定類型參數的數據結構
• 支持多模塊項目（從指定Jar包中解析源碼或數據結構）

實現方式

• 解析源碼文件，通過源碼及其中的註釋生成文檔信息。目前爲止註釋中使用的Tag都是Java註釋的標準Tag，後續可能會添加一些必要的自定義Tag，甚至有可能提供Tag擴展機制 —— 由使用者自定義Tag，同時自定義Tag的處理方式。

• 一想到生成Java RESTful API文檔，首先就是想到Java API文檔是如何生成的，所以解析源碼的方式沒有選擇使用com.github.javaparser » javaparser-core或者com.thoughtworks.qdox » qdox，而是選擇JDK自己的Javadoc Tool （https://docs.oracle.com/en/java/javase/12/tools/javadoc.html），Javadoc Tool對應的API是Javadoc API（https://docs.oracle.com/en/java/javase/12/docs/api/jdk.javadoc/module-summary.html）

• 由於作者還在使用Java8，所以該項目的實現完全是基於Javadoc API 舊版

  • Package com.sun.tools.javadoc (https://docs.oracle.com/en/java/javase/12/docs/api/jdk.javadoc/com/sun/tools/javadoc/package-summary.html)
  • Package com.sun.javadoc (https://docs.oracle.com/en/java/javase/12/docs/api/jdk.javadoc/com/sun/javadoc/package-summary.html)

  其中：

  Module jdk.javadoc
  Package com.sun.tools.javadoc
  This package and its contents are deprecated and may be removed in a future release. See javax.tools.ToolProvider.getSystemDocumentationTool and javax.tools.DocumentationTool for replacement functionality.

  Module jdk.javadoc
  Package com.sun.javadoc
  Note: The declarations in this package have been superseded by those in the package jdk.javadoc.doclet. For more information, see the Migration Guide in the documentation for that package.

  @Deprecated(since="9",forRemoval=true)
  public class Main extends Object
  

  可以看出，舊版Javadoc API自 Java9 已經被標記遺棄，在不久的將來將被移除，但是值得慶幸，直到最新的大版本 Java12 該API還未移除，所以使用 Java12 及以前版本的用戶可以放心使用，後續作者會提供新版API支持。

• UI界面是基於 create-react-app 與 antd 開發的single page application ——
  smalldoc-antd-react-ui（https://github.com/liuhuagui/smalldoc-antd-react-ui）

使用

示例爲spring-boot項目，使用 application.yml 做爲配置文件

引入依賴

<dependency>
    <groupId>com.github.liuhuagui</groupId>
    <artifactId>smalldoc-spring-boot-starter</artifactId>
    <version>2.3</version>
</dependency>

配置

接口文檔通常在開發時使用，只需要保證文檔配置在開發環境下生效 —— spring.profiles.active=dev

server: 
  port: 8080
  servlet:
    context-path: /my-project
spring: 
  profiles:
    active: dev
---
spring:
  profiles: dev
smalldoc:
  source-paths: #額外的源碼路徑（項目的源碼路徑默認已經包含在內，不需要再添加）
    - 'D:\Workspaces\myBeanProject\my-bean\src\main\java'
    - 'D:\Maven\Repositories\repository\com\aliyun\aliyun-java-sdk-core\3.5.0'
  packages:
    - quantity.knowledgebase
    - my.bean
    - com.aliyuncs.auth.sts
  project-name: 我的文檔
  enabled: true #默認爲true
  url-pattern: /smalldoc/* #默認爲/smalldoc/*

訪問地址

• URL: http://192.168.1.76:8080/my-project/smalldoc/
• METHOD: GET

接口源碼

/**
 * 文章的創建，編輯，發佈，自定義
 * @author KaiKang [email protected]
 */
@RestController
@RequestMapping("w")
public class WriteArticleController {
    /**
     * 原創文章在編輯中保存
     * @param content 內容
     * @param oaCopy  原創文章副本
     * @return data-草稿ID
     * @author KaiKang [email protected]
     */
    @PostMapping(path = "o/save_draft",produces = {"text/plain", "application/json;charset=UTF-8"},consumes = "application/x-www-form-urlencoded")
    public Result<Long> saveOriginalDraft(String content, OriginalArticleCopy oaCopy, HttpServletRequest request) {
        return writeArticleService.saveOriginalDraft(content, oaCopy);
    }

    /**
     * 這只是一個測試接口
     * @param content 內容
     * @return 返回數據
     * @author KaiKang [email protected]
     */
    @GetMapping(path = "o/save",produces = {"text/plain", "application/json;charset=UTF-8"})
    public Result<OriginalArticle> save(String content, HttpServletRequest request) {
        return null;
    }
}

接口文檔

文檔API（用來實現自定義UI）

• URL: http://192.168.1.76:8080/my-project/smalldoc/
• METHOD: POST
  

注意

• source-paths 配置項表示額外的源碼路徑，項目的源碼路徑默認已經包含在內，不需要額外添加，只需要指定掃描的包，比如：my.project.controller
• 程序只會解析類名爲*Controller的源代碼中的接口信息（規範）
• 程序暫未支持Linux環境，在項目打包部署之前，記得關閉文檔功能，關閉方式多種多樣，比如：
  1. spring.profiles.active=*(* 只要不是dev即可)，不再激活開發環境配置
  2. smalldoc.enabled=false，關閉啓用
  3. 修改依賴作用域爲test後再進行打包，這樣連smalldoc的jar包都不會被打包進去（推薦）

      <dependency>
        	<groupId>com.github.liuhuagui</groupId>
        	<artifactId>smalldoc-spring-boot-starter</artifactId>
        	<version>2.3</version>
        	<scope>test</scope>
      </dependency>
     

社區

如果在使用過程中需要幫助或者希望項目增加某些功能，歡迎issue —— https://github.com/liuhuagui/smalldoc/issues