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 类
- UserController
- UserCreateReqVO
- UserListReqVO
- UserRespVO
2.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 的接口文档，所以无需使用它。
具体的使用示例如下：3.2 @Ignore 注解
@Ignore 注解，比较好理解，实现接口或字段的忽略。
具体的使用示例如下：
// 示例一：声明在 Controller 类上，忽略该 Controller 的所有接口
@Ignore
public 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
*/
@Controller
public class UserController {}② 在接口方法上使用 @description 注释，则可以在接口方法下面额外添加一行说明。示例代码如下：
/**
* 获得用户列表
*
* @param listReqVO 列表筛选条件
* @return 用户列表
* @description 不同的前端界面，可能有不同的查询诉求，通过该接口统一满足。
*/
@GetMapping("list")
public List<UserRespVO> list(UserListReqVO listReqVO){
return null;
}