java文档注释生产api没有注释_一个神奇的没有springboot注释的api文档生成器---JApiDocs...
入門
支持JDK：1.8+
快速開始
第一步：添加依賴
maven:
io.github.yedaxia
japidocs
1.4.3
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> list(UserListForm listForm){
return null;
}
/**
* 保存用戶
* @param userForm
*/
@PostMapping(path = "save")
public ApiResult 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 saveUser(@RequestBody UserForm userForm){
return null;
}
ApiResult表明了該接口返回的數據結構，經過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> 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 controllerNodeList){
// 實現你自己的功能需求
}
}
第二步：添加插件
config.addPlugin(new CustomPlugin());
常見問題
1、如何排查錯誤？
關閉自動生成config.setAutoGenerate(Boolean.FALSE)，使用@ApiDoc 來一個個接口導出排查問題。
2、多模塊找不到相關類源碼？
如果源碼路徑沒有全部識別出來，可以通過config.addJavaSrcPath來添加模塊的源碼路徑，注意要添加到src/main/java這一級。
總結
以上是生活随笔為你收集整理的java文档注释生产api没有注释_一个神奇的没有springboot注释的api文档生成器---JApiDocs...的全部內容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： java scanner字符串_Java
- 下一篇： 运行程序时java后面跟的是文件名对吗_