JApiDocs真香：以后再也不想用Swagger了

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 的接口文档，所以无需使用它。

具体的使用示例如下：

// 示例一
@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<UserRespVO> list(UserListReqVO listReqVO){
    return null;
}