Spring Boot API 接口文档 JApiDocs 入门
2.1 引入依赖
在 pom.xml 文件中，引入 japidocs 的依赖。
io.github.yedaxia japidocs 1.4.4
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 注释，所以我们需要在相关的类、方法、属性上，进行添加。示例代码如下图：
2.4 简单测试
示例项目搭建完成，我们来简单测试下。
① 执行 TestJApiDocs 类，生成 JApiDocs 接口文档。结果如下图所示：
② 点击 index.html 文件，查看 HTML 接口文档。如下图所示：
后续，我们可以部署到 Nginx 下，提供给前端小伙伴查看接口文档。
③ 点击 *-api-docs.md 文件，查看 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 的所有接口 @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 list(UserListReqVO listReqVO){ return null; }
666. 彩蛋
至此，我们已经“精通” JApiDocs 的入门使用，通过在接口上添加 Java 注释，即可生成 HTTP API 的接口文档，非常的便捷。更多内容，胖友可以阅读《JApiDocs 官方文档》。
不过真正在团队中使用的话，艿艿还是会选择 Swagger，而不是 JApiDocs 作为接口文档的工具。主要有如下原因：
① JApiDocs 界面不提供接口调试功能，这个在日常开发中，还是非常高频使用的一个功能。
② JApiDocs 支持对接 RAP 接口平台，不支持我们使用的 YApi 接口平台，需要进行二次的插件开发。而 YApi 默认提供对 Swagger 的集成，可以直接采集接口信息。
良心艿：随着公司项目越来越多，我们会引入接口平台，提供统一的入口，查看所有项目的接口文档。
同时，接口平台往往提供接口的 mock 能力，可以更好的实现前后端的并行开发，提升开发效率和体验。
想要进一步了解的胖友，可以阅读《芋道 Spring Boot API 接口文档 Swagger 入门》文章的「4. 更强大的 YApi」小节。
③ JApiDocs 是基于 注释 作为接口信息的数据来源，而 Java 注释的定制化能力是弱于 注解 的。
例如说，Swagger 的 @ApiImplicitParam 注解，可以使用 required 属性声明是否必填，使用 example 属性声明参数示例，这个在 Java 注释是非常难以实现的。
很多时候，我们会认为 Swagger 使用注解的侵入性很强，是因为在参数较多的接口方法上，会写一大片的 @ApiImplicitParam 注解，导致看起来会乱糟糟的。这个其实非常好解决，艿艿推荐对于复杂参数的接口，统一定义 POJO 类。示例如下：
