一個無需注解的 SpringBoot API文檔生成神器，相當哇塞！

JApiDocs是一個無需額外注解、開箱即用的SpringBoot接口文檔生成工具。

編寫和維護API文檔這個事情，對于後端程式員來說，是一件惱人但又不得不做的事情，我們都不喜歡寫文檔，但除非項目前後端代碼都是自己寫的，否則API文檔将是前後端協作中一個不可或缺的溝通界面。

既然不可避免，那就想辦法弄個輪子吧。人生苦短，必須偷懶。

無圖無真相，生成文檔的效果如下：

功能特性

1、代碼即文檔

JApiDocs是通過直接解析SpringBoot的源碼文法來工作的，是以隻要Controller的文法符合一定的代碼規範，有合理的注釋，就可以直接導出文檔。

2、支援導出HTML

便捷的導航和接口檢視界面；可本地預覽，或者部署到HTTP伺服器。推薦部署到伺服器，友善前後端展開協作。

3、同步導出用戶端Model代碼

支援導出Android端的 Java 和iOS端的 Object C Model代碼，減少前端程式員的重複編碼工作。

4、更多特性

支援接口搜尋；支援不同版本和英文文檔；自定義擴充等。

簡潔的文檔

再好用的東西，如果沒有文檔說明，别人也無從入手。為了讓大家盡快上手，JApiDocs準備了一份極簡的文檔說明，確定你在幾分鐘就能用上JApiDocs。

花5分鐘不到就能認識一個提高工作效率的工具，讓你把更多的時間花在更加有價值的事情上，你确認不看一下嗎？

倉庫位址：https://github.com/YeDaxia/JApiDocs

中文文檔：https://japidocs.agilestudio.cn/#/zh-cn/

支援接口搜尋；支援不同版本和英文文檔；自定義擴充等。

入門

支援JDK：1.8+

快速開始

第一步：添加依賴

maven:

<dependency>
  <groupId>io.github.yedaxia</groupId>
  <artifactId>japidocs</artifactId>
  <version>1.3</version>
</dependency>
           

gradle:

compile 'io.github.yedaxia:japidocs:1.3'
           

第二步：配置參數

你可以在任意一個main入口運作下面的代碼：

DocsConfig config = new DocsConfig();
config.setProjectPath("your springboot project path"); // 項目根目錄
config.setProjectName("ProjectName"); // 項目名稱
config.setApiVersion("V1.0");       // 聲明該API的版本
config.setDocsPath("your api docs path"); // 生成API 文檔所在目錄
config.setAutoGenerate(Boolean.TRUE);  // 配置自動生成
Docs.buildHtmlDocs(config); // 執行生成文檔
           

如果沒有意外，執行完上面的代碼後，你就可以在配置的目錄中看到生成的文檔了。

編碼規範

JApiDocs是通過解析Java源碼來實作的，要使得JApiDocs正确工作，需要你在項目中的Controller書寫遵循一定的編碼規範。

你可以結合源碼中 SpringDemo 這個子產品來對照了解。

1. 添加必要的代碼注釋

其中類注釋會對應到一級接口分組，你也可以通過@description來指定分組名稱；JApiDocs 會通過 @param 來尋找接口參數和進一步解析參數的内容。

/**
 * 使用者接口
 */
@RequestMapping("/api/user/")
@RestController
public class UserController {

    /**
     * 使用者清單
     * @param listForm
     */
    @RequestMapping(path = "list", method = {RequestMethod.GET,  RequestMethod.POST}  )
    public ApiResult<PageResult<UserVO>> list(UserListForm listForm){
        return null;
    }

    /**
     * 儲存使用者
     * @param userForm
     */
    @PostMapping(path = "save")
    public ApiResult<UserVO> saveUser(@RequestBody UserForm userForm){
        return null;
    }

    /**
     * 删除使用者
     * @param userId 使用者ID
     */
    @PostMapping("delete")
    public ApiResult deleteUser(@RequestParam Long userId){
        return null;
    }
}
           

如果送出的表單是 application/x-www-form-urlencoded 類型的key/value格式，你可以在 SpringBoot 端通過在 @param 參數後添加字段解釋或者在相關的JavaBean對象裡面添加解釋：

// 直接在java的 @param 注解中
@param userId 使用者ID
           

// 在FormBean對象中
public class UserListForm extends PageForm{
    private Integer status; //使用者狀态
    private String name; //使用者名
}
           

這種格式對于到文檔中的參數描述将是表格的形式：

如果送出的表單是 application/json 類型的json資料格式，對應 SpringBoot 中的 @RequestBody 注解，在文檔中則是 json 格式顯示：

{
  "id": "long //使用者ID",
  "name": "string //使用者名",
  "phone": "long //電話",
  "avatar": "string //頭像",
  "gender": "byte //性别"
}
           

2. 接口聲明傳回對象

我們知道，如果Controller聲明了@RestController，SpringBoot會把傳回的對象直接序列成Json資料格式傳回給前端。JApiDocs也利用了這一特性來解析接口傳回的結果，但由于JApiDocs是靜态解析源碼的，是以你要明确指出傳回對象的類型資訊，JApiDocs支援繼承、泛型、循環嵌套等複雜的類解析。

比如上面的saveUser接口：

/**
 * 儲存使用者
 * @param userForm
 */
@PostMapping(path = "save")
public ApiResult<UserVO> saveUser(@RequestBody UserForm userForm){
    return null;
}
           

ApiResult<UserVO>表明了該接口傳回的資料結構，經過JApiDocs處理後是這樣的：

{
  "code": "int",
  "errMsg": "string",
  "data": {
    "userId": "string //使用者id",
    "userName": "string //使用者名",
    "friends": [
      {
        "userId": "string //使用者id",
        "userName": "string //使用者名"
      }
    ],
    "readBooks": [
      {
        "bookId": "long //圖書id",
        "bookName": "string //圖書名稱"
      }
    ],
    "isFollow": "boolean //是否關注"
  }
}
           

如果你不是通過傳回對象的形式，你也可以通過JApiDocs提供的@ApiDoc注解來聲明傳回類型，你可以參考@ApiDoc章節的相關配置内容。

3. 接口對象在源碼中

我們知道，經過編譯後的 class 位元組碼中是沒有注釋資訊的，如果要通過反射位元組碼的方式來實作，則不可避免要引入運作時注解，這樣會增加使用成本， 考慮到這一點，JApiDocs 從第二個版本之後就改成了使用解析源碼的方式，而不是反射位元組碼的思路來實作了，但這樣直接導緻的缺陷就是：所有的 Form Bean (表單)對象和傳回對象就必須在項目的源碼中，否則就無法解析了，如果你們項目的JavaBean對象是通過jar包的形式提供的， 那很遺憾，JApiDocs将無法支援。

進階配置

@ApiDoc

JApiDocs 預設隻導出聲明了@ApiDoc的接口，我們前面通過設定 config.setAutoGenerate(Boolean.TRUE) 來解除了這個限制。

如果你不希望把所有的接口都導出，你可以把autoGenerate設定關閉，在相關Controller類或者接口方法上通過添加@ApiDoc來确定哪些接口需要導出。

當@ApiDoc聲明在接口方法上的時候，它還擁有一些更靈活的設定，下面我們來看一下：

• result: 這個可以直接聲明傳回的對象類型，如果你聲明了，将會覆寫SpringBoot的傳回對象
• url: 請求URL，擴充字段，用于支援非SpringBoot項目
• method: 請求方法，擴充字段，用于支援非SpringBoot項目

例子：

@ApiDoc(result = AdminVO.class, url = "/api/v1/admin/login2", method = "post")
           

@Ignore

如果你不想導出對象裡面的某個字段，可以給這個字段加上@Ignore注解，這樣JApiDocs導出文檔的時候就會自動忽略掉了：

例子:

public class UserForm{
    @Ignore
    private Byte gender; //性别
}
           

自定義代碼模闆

JApiDocs 除了支援文檔導出，目前也支援生成了 Android 和 iOS 的傳回對象代碼，對應 Java 和 Object-C 語言， 如果你想修改代碼模闆，可以通過以下的方法：

第一步：定義代碼模闆

把源碼中library項目resources目錄下的代碼模闆拷貝一份，其中，IOS_表示 Object-C 代碼模闆，JAVA_開頭表示 Java代碼， 模闆中類似${CLASS_NAME}的符号是替換變量，具體含義你可以結合生成的代碼進行了解，然後按照你想要的代碼模闆進行修改即可。

第二步：選擇新的模闆

通過DocsConfig配置模闆路徑替換成新的模闆：

docsConfig.setCodeTplPath("模闆路徑");
           

添加更多功能

JApiDocs 提供了插件接口，你可以通過插件接口來實作更多豐富的功能，下面介紹如何添加插件：

第一步：實作 IPluginSupport 接口

public class CustomPlugin implements IPluginSupport{

    @Override
    public void execute(List<ControllerNode> controllerNodeList){
        // 實作你自己的功能需求
    }
}
           

第二步：添加插件

config.addPlugin(new CustomPlugin());           

來源：TJ君