使用 JApiDocs 生成静态文档

今天分享一个生成静态文档的工具 JApiDocs。

首先看一下生成效果

和 Swagger 对比

优点

• 和 Swagger 相比，JApiDocs 对现有代码无任何侵入，只需按 javadoc 格式添加注释，就能生成文档。

缺点

• JApiDocs 适合生成静态文档，目前没有 Swagger 的调试功能。
• 需要解析的对象必须在项目的源码中，不支持 Jar 包内的注释解析。

下面来快速入门

首先引入依赖

<dependency>
  <groupId>io.github.yedaxia</groupId>
  <artifactId>japidocs</artifactId>
  <version>1.4</version>
</dependency>

按照 javadoc 格式添加注释的 UserController

/**
 * 用户 Controller
 * @author zhuo
 */
@RequestMapping("/api/user/")
@RestController
public class UserController {

    /**
     * 用户列表
     * @param user
     */
    @RequestMapping(path = "list", method = {RequestMethod.GET,  RequestMethod.POST}  )
    public BaseResponse<List<UserVO>> list(UserVO user){
        return null;
    }

    /**
     * 保存用户
     * @param user
     */
    @PostMapping(path = "save")
    public BaseResponse<UserVO> saveUser(@RequestBody UserVO user){
        return null;
    }

    /**
     * 删除用户
     * @param userId 用户ID
     */
    @PostMapping("delete")
    public BaseResponse deleteUser(@RequestParam Long userId){
        return null;
    }

}

实体 UserVO

/**
 * 用户对象
 * @author zhuo
 */
public class UserVO {
    /** 用户 ID */
    private Long id;
    /** 用户名 */
    private String userName;
// getter setter 略
}

运行以下代码即可生成文档

public class JApiDocsApplication {

    public static void main(String[] args) {
        // 自动获取当前项目路径
        String projectPath = System.getProperty("user.dir") + "/spring-boot-2.x-samples/spring-boot-samples-japidocs";
        DocsConfig config = new DocsConfig();
        // 项目根目录
        config.setProjectPath(projectPath);
        // 项目名称
        config.setProjectName("SpringBoot 集成 JApiDocs 生成");
        // 声明该API的版本
        config.setApiVersion("V1.0");
        // 生成API 文档所在目录
        config.setDocsPath(projectPath + "/docs");
        // 配置自动生成
        config.setAutoGenerate(Boolean.TRUE);
        // 执行生成文档
        Docs.buildHtmlDocs(config);
    }
}

更多配置参考:

JApiDocs 官方文档：https://japidocs.agilestudio.cn/#/

代码示例

本文的完整工程可以查看下面仓库中的 spring-boot-samples-japidocs 目录：

• Github：https://github.com/zhuyizhuo/spring-boot-samples/
• Gitee：https://gitee.com/zhuyizhuo/spring-boot-samples/

如果您觉得本文不错，欢迎Star支持，您的关注是我坚持的动力！