JApiDocs教程
前言
- 作為一名優秀的程序員來說，由於涉及到要與前端進行對接，所以避免不了的就是寫接口文檔。寫完接口文檔，一旦代碼返回結果，參數等出現變動，接口文檔還得隨之改動，十分麻煩，違背了我們簡單，快速，低bug的開發初衷。
- 所以，自動生成接口文檔的工具就出現了。大家最熟悉的應該就是swagger了，我並沒有使用過swagger，雖然它比較健壯，穩定。但是由於它的規范很復雜，需要將代碼變動的地方也很多。所以我使用了JApiDocs這個工具來為我的項目自定生成接口文檔。
- 它的優點就是，相對於springboot以及ssm開發模式而言，它的改動都不是很大，規范一下代碼，就可以輕松獲取接口文檔了。
- 問題：參數為實體類對象時，直接顯示對象里的所有字段。而真正使用的字段只有一部分。大體沒什么毛病，界面也很簡潔美觀。大家如果有解決參數精准顯示的想法，可以在評論區一起討論下。
一、Maven依賴
<!-- JApiDocs -->
<dependency>
<groupId>io.github.yedaxia</groupId>
<artifactId>japidocs</artifactId>
<version>1.4.3</version>
</dependency>
二、代碼規范
為什么要進行代碼規范？
- JApiDocs會根據固定的格式，來為我們解析出相應的接口文檔，相對比與swagger來說，JApiDocs的格式相對來說是很簡單的，springboot開發的項目使用起來改動不大，同時還能使我們的代碼規范，簡潔，一致。所以我們只要遵循以下幾點就能得到規整的接口文檔了。
以下都是針對於controller模塊：
1. 分組名稱 @description
注：官方文檔中注明分組名稱@description，但是實際應用中不需要加入注解，像下例所示，直接寫注釋即可。（類上寫不寫都行，方法上如果加上@description反而不顯示）
例：
/**
* 用戶接口
*/
/*注意：這里不能空行，否則注釋名無法顯示*/
@RequestMapping("test")
@Controller
public class testInterface {
@Autowired
private RoleService roleService;
/**
* 保存用戶
*/
@PostMapping("advice")
public RoleInfo getAdviceList(String docId){
return roleService.FindRoleBydocId(docId);
}
}
效果圖：
2. 接口參數（JApiDocs 會通過 @param 來尋找接口參數和進一步解析參數的內容）
注：注釋一定要放在@注解的上面，否則參數會不顯示
（1）格式：接口參數 @param 字段 字段解釋
例：
/**
* @description 保存用戶
* @param docId 醫生id
*/
@PostMapping("advice")
public RoleInfo getAdviceList(String docId){
return roleService.FindRoleBydocId(docId);
}
效果圖：
（2）在相應的bean對象里添加注釋
例：
public class RemindInfo implements Serializable {
private long remindId; //提醒id
private String remindContent; //提醒信息
private java.sql.Timestamp remindTime; //提醒時間
}
效果圖：
注：字段后的注釋一定都要寫上，否則會報下面的錯誤：
（3）使用@RequestBody 注解json格式的參數
效果圖：
3. 返回對象
（1）@RestController 或 @ResponseBody
返回json數據類型
例：
/**
* 用戶接口
*/
@RequestMapping("/test")
@RestController
public class testInterface {
@Autowired
private RoleService roleService;
/**
* 保存用戶
* @param docId 醫生id
*/
@ApiDoc
@PostMapping("advice")
public RoleInfo getAdviceList(String docId){
return roleService.FindRoleBydocId(docId);
}
}
效果圖：
（2）請求類型
@PostMapping("advice")/@GetMapping("advice")
public RoleInfo getAdviceList(String docId){
return roleService.FindRoleBydocId(docId);
}
效果圖： 
沒有指定具體類型時：
注：返回參數不能指向不明，如：Object，否則會報
Exception in thread "main" io.github.yedaxia.apidocs.exception.JavaFileNotFoundException: Cannot find java file 的錯誤。
4、高級配置
（1）@ApiDoc
a.實現
JApiDocs 默認只導出聲明了@ApiDoc的接口，我們前面通過設置config.setAutoGenerate(Boolean.TRUE) 來解除了這個限制。如果你不希望把所有的接口都導出，你可以把autoGenerate設置關閉，在相關Controller類或者接口方法上通過添加@ApiDoc來確定哪些接口需要導出。
b.其他設置
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(){}
(2)@Ignore (忽略Controller，接口，字段)
例：忽略Controller
@Ignore
public class UserController {
}
三、配置參數
在任意一個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); // 執行生成文檔
執行結果類似效果圖：
四、導出格式
（1）Markdown
config.addPlugin(new MarkdownDocPlugin());
（2）導出 pdf 或者 word
可以通過 pandoc 把 markdown 格式轉成 pdf 或者 word 格式。
五、自定義代碼模板
JApiDocs 除了支持文檔導出，目前也支持生成了 Android 和 iOS 的返回對象代碼，對應 Java 和 Object-C 語言， 如果你想修改代碼模板，可以通過以下的方法：
（1）定義代碼模板
把源碼中library項目resources目錄下的代碼模板拷貝一份，其中，IOS_表示 Object-C 代碼模板，JAVA_開頭表示 Java代碼， 模板中類似${CLASS_NAME}的符號是替換變量，具體含義你可以結合生成的代碼進行理解，然后按照你想要的代碼模板進行修改即可。
（2）選擇新的模板
通過DocsConfig配置模板路徑替換成新的模板：
docsConfig.setResourcePath("模板路徑");
六、添加更多功能
JApiDocs 提供了插件接口，你可以通過插件接口來實現更多豐富的功能，下面介紹如何添加插件：
（1）實現 IPluginSupport 接口
public class CustomPlugin implements IPluginSupport{
@Override
public void execute(List<ControllerNode> controllerNodeList){
// 實現你自己的功能需求
}
}
（2）添加插件
config.addPlugin(new CustomPlugin());
七、問題的解決
1、如何排查錯誤？
關閉自動生成config.setAutoGenerate(Boolean.FALSE)，使用@ApiDoc 來一個個接口導出排查問題。
2、多模塊找不到相關類源碼？
如果源碼路徑沒有全部識別出來，可以通過config.addJavaSrcPath來添加模塊的源碼路徑，注意要添加到src/main/java這一級。
八、自定義注釋模板
這是我針對JApiDocs，對我的模板進行了一定的調整，以方便對JApiDocs的使用，大家可以參考一下。
（1）Live Templates
/**
* TODO
* @create_by: 作者名字
* @create_time: $date$ $time$
* $params$
* @return $return$
*/
（2）File Header
/**
* @Author 作者名字
* @Date ${DATE} ${TIME}
* @description ${description}
* @Version 1.0
*/
具體如何實現自定義方法注釋，類注釋。可以參考下面的文章：
JApiDocs官方文檔地址：