來源：https://mp.weixin.qq.com/s/XgC6fBB_RlwxTNthk5kEAQ
1. 概述
Swagger最麻煩的就是需要在 Controller 上添加一堆 @ApiOperation、@ApiOperation 註解，對代碼有一定的侵入性。今天，筆者推薦一個不需要加註解的解決方案。
抱大腿
這就是 JApiDocs ，它可以基於 Controller上的 Java 注釋，直接生成接口文檔。效果如下圖所示：
效果圖
友情提示GitHub 地址是：https://github.com/YeDaxia/JApiDocs 。
2. 快速入門
看完了 JApiDocs 生成的接口文檔的效果，我們一起來快速入門下。完整的示例項目，可見 https://github.com/YunaiV/SpringBoot-Labs/tree/master/lab-24/lab-24-apidoc-japidocs 地址，代碼如下圖所示：
項目代碼
下面，我們來瞅一瞅如何使用~
2.1 引入依賴
在 pom.xml 文件中，引入 japidocs 的依賴。
<dependency> <groupId>io.github.yedaxia</groupId> <artifactId>japidocs</artifactId> <version>1.4.4</version></dependency>2.2 創建 JApiDocs 配置
創建 TestJApiDocs 類，作為 JApiDocs 的配置，生成接口文檔。代碼如下：
public class TestJApiDocs { public static void main(String[] args) { // 1. 創建生成文檔的配置 DocsConfig config = new DocsConfig(); config.setProjectPath("/Users/yunai/Java/SpringBoot-Labs/lab-24/lab-24-apidoc-japidocs"); // 項目所在目錄 config.setDocsPath("/Users/yunai/Downloads/"); // 生成 HTML 接口文檔的目標目錄 config.setAutoGenerate(true); // 是否給所有 Controller 生成接口文檔 config.setProjectName("示例項目"); // 項目名 config.setApiVersion("V1.0"); // API 版本號 config.addPlugin(new MarkdownDocPlugin()); // 使用 MD 插件，額外生成 MD 格式的接口文檔 // 2. 執行生成 HTML 接口文檔 Docs.buildHtmlDocs(config); }}偷懶艿：代碼比較簡單，胖友看下注釋，秒懂~
稍後，我們執行 #main(...) 方法，就可以使用 JApiDocs 生成接口文檔。
2.3 代碼注釋
JApiDocs 是通過解析 Controller 源碼上的 Java 注釋，所以我們需要在相關的類、方法、屬性上，進行添加。示例代碼如下圖：
Java 類
UserControllerUserCreateReqVOUserListReqVOUserRespVO2.4 簡單測試
示例項目搭建完成，我們來簡單測試下。
① 執行 TestJApiDocs 類，生成 JApiDocs 接口文檔。結果如下圖所示：
生成結果
② 點擊 index.html 文件，查看 HTML 接口文檔。如下圖所示：
HTML 接口文檔
後續，我們可以部署到 Nginx 下，提供給前端小夥伴查看接口文檔。
③ 點擊 *-api-docs.md 文件，查看 Markdown 接口文檔。如下圖所示：
Markdown 接口文檔
3. 高級用法
本小節，我們來學習下 JApiDocs 的高級用法。
友情提示：在 99.99% 的場景下，不會使用到，所以胖友可以選擇忽略不看。如果使用到，請胖友直接去錘死狗芳。
JApiDocs 自定義了 @ApiDoc 和 @Ignore 註解，用於針對指定接口，進行自定義的配置。下面，我們來瞅一瞅哦。
良心艿：可能會有胖友說，JApiDocs 的註解不是和 Swagger 的註解一樣，也對代碼有入侵嗎？確實是的，但是比 Swagger 的註解入侵性會低一些，並且基本不需要使用到。
3.1 @ApiDoc 註解
@ApiDoc 註解，聲明在接口方法上，通過它的四個屬性，進行靈活配置。
result 屬性：直接聲明返回結果的類型。如果你聲明了，將會覆蓋方法返回結果的類型。stringResult 屬性：返回字符串。在返回結果比較簡單，而不想創建一個專門的返回類，則可以考慮使用這個屬性。友情提示：建議返回結果是否簡單，還是創建一個對應的返回類，可維護性更好。url 屬性：請求 URL。擴展欄位，用於支持非 SpringMVC 的項目。友情提示：JApiDocs 提供了 SpringControllerParser 類，支持解析 SpringMVC 的註解。對於一些老項目，例如說使用 Struts 框架，則需要通過 url 屬性來聲明。當然，更加推薦自定義一個針對 Struts 的 Parser 解析器，每個接口都手寫，挺麻煩的。method 屬性：請求 Method。擴展欄位，用於支持非 SpringMVC 項目。@ApiDoc 註解還有一個作用，聲明該接口需要導出文檔。不過因為一般我們會設置 DocsConfig 的 autoGenerate 屬性為 true，默認導出所有 Controller 的接口文檔，所以無需使用它。
具體的使用示例如下：
// 示例一@ApiDoc(result = AdminVO.class, url = "/api/v1/admin/login2", method = "post")// 示例二：針對 `stringResult` 屬性@ApiDoc(stringResult = "{code: 0, data: 'success'}")@GetMapping(value = "custom-json")public Map customJsonResult() {}3.2 @Ignore 註解
@Ignore 註解，比較好理解，實現接口或欄位的忽略。
具體的使用示例如下：
// 示例一：聲明在 Controller 類上，忽略該 Controller 的所有接口@Ignorepublic class UserController {}// 示例二：聲明在接口方法上，忽略該接口@Ignore@PostMapping("save")public ApiResult saveUser() {}// 示例三：聲明在接口使用到的對象的屬性上，忽略該屬性public class UserCreateReqVO { @Ignore private Integer age; }3.3 @description 注釋
通過 @description 注釋，主要有兩種使用場景。
友情提示：由於 @description 注釋不是 Java 注釋中自帶的標籤，所以 IDEA 會存在黃色報警的情況，需要手動添加下，去除告警。
① 在 Controller 類上使用 @description 注釋，將會作為該 Controller 在接口文檔上的導航標題，而不會使用上面的注釋內容。示例代碼如下：
/** * 用戶 Controller，提供用戶基本信息的 CRUD 的功能 * * @description 用戶 API */@Controllerpublic class UserController {}② 在接口方法上使用 @description 注釋，則可以在接口方法下面額外添加一行說明。示例代碼如下：
/** * 獲得用戶列表 * * @param listReqVO 列表篩選條件 * @return 用戶列表 * @description 不同的前端界面，可能有不同的查詢訴求，通過該接口統一滿足。 */@GetMapping("list")public List<UserRespVO> list(UserListReqVO listReqVO){ return null;}