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

項目

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

爲何要造輪子？

• 強迫症患者，接受不了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 （docs.oracle.com/en/java/jav… Tool對應的API是Javadoc API（docs.oracle.com/en/java/jav…

• 因爲做者還在使用Java8，因此該項目的實現徹底是基於Javadoc API 舊版

  • Package com.sun.tools.javadoc (docs.oracle.com/en/java/jav…)
  • Package com.sun.javadoc (docs.oracle.com/en/java/jav…)

  其中：

  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（github.com/liuhuagui/s…

使用

示例爲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 799600902@qq.com */
@RestController
@RequestMapping("w")
public class WriteArticleController {
    /** * 原創文章在編輯中保存 * @param content 內容 * @param oaCopy 原創文章副本 * @return data-草稿ID * @author KaiKang 799600902@qq.com */
    @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 799600902@qq.com */
    @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 —— github.com/liuhuagui/s…