一個神奇的沒有springboot注釋的api文檔生成器---JApiDocs

入門

支持JDK：1.8+

快速開始

第一步：添加依賴

maven:

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

gradle:

compile 'io.github.yedaxia:japidocs:1.4.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; //用戶名
}

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

參數名	類型	必須	描述
status	int	否	用戶狀態
name	string	否	用戶名

如果提交的表單是 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 字節碼中是沒有注釋信息的。所以為了讓JApiDcos能更好地工作，你的表單Bean類和返回類最好在源碼中，否則生成的文檔將會缺失說明信息。 在1.4.2版本中，JApiDocs在找不到源碼的情況下（依賴類在jar包中）也會通過嘗試反射的方式來解析字段信息，但這樣就沒有說明信息了。

后續會計划通過關聯源碼的形式來解決這個問題。

高級配置

@ApiDoc

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

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

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

• result: 這個可以直接聲明返回的對象類型，如果你聲明了，將會覆蓋SpringBoot的返回對象
• stringResult：返回字符串，在返回結果比較簡單，而不想創建一個專門的返回類，則可以考慮使用這個屬性。
• url: 請求URL，擴展字段，用於支持非SpringBoot項目
• method: 請求方法，擴展字段，用於支持非SpringBoot項目

例子：

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

stringResult 實例，在文檔中將會自動格式化json字符串：

@ApiDoc(stringResult = "{code: 0, data: 'success'}")
@GetMapping(value = "custom-json")
public Map customJsonResult(){}

@Ignore

忽略Controller

你只需要在Controller類上添加該注解即可，這樣，整個Controller的接口都會被忽略掉：

@Ignore
public class UserController { 

}

忽略接口

不難理解，就是在接口方法中添加@Ignore注解：

@Ignore
@PostMapping("save")
public ApiResult saveUser(){
  return null;
}

忽略字段

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

例子:

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

@description

在Controller類上使用

在類上使用@description，將會作為該Controller在文檔上的導航標題，而不會使用上面的注釋內容。

/**
 * 演示一些比較特殊的聲明方法
 *
 * @description 管理員接口
 * @author yeguozhong yedaxia.github.com
 */
@Controller
public class AdminController {

在接口方法上使用

在方法中使用，則可以在接口方法下面添加一行說明：

/**
  * 用戶列表
  * @description 這是一行說明
  * @param listForm
  * @author yedaxia
  */
  @RequestMapping(path = "list", method = {RequestMethod.GET,  RequestMethod.POST}  )
  public ApiResult<PageResult<UserVO>> list(UserListForm listForm){}

導出更多格式

導出markdown

config.addPlugin(new MarkdownDocPlugin());

導出 pdf 或者 word

你可以通過 pandoc 把 markdown 格式轉成 pdf 或者 word 格式。

自定義代碼模板

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

第一步：定義代碼模板

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

第二步：選擇新的模板

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

docsConfig.setResourcePath("模板路徑");

添加更多功能

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

第一步：實現 IPluginSupport 接口

public class CustomPlugin implements IPluginSupport{

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

第二步：添加插件

 config.addPlugin(new CustomPlugin());

常見問題

1、如何排查錯誤？

關閉自動生成config.setAutoGenerate(Boolean.FALSE)，使用@ApiDoc 來一個個接口導出排查問題。

2、多模塊找不到相關類源碼？

如果源碼路徑沒有全部識別出來，可以通過config.addJavaSrcPath來添加模塊的源碼路徑，注意要添加到src/main/java這一級。