JApiDocs 无需额外注解的 SpringBoot API文档生成工具踩过的坑，解放接口文档的编写

最近改用smart-doc，使用方便，功能更加强大，官网地址

Wiki - Gitee.com

被写接口文档难受了好久,使用swagger要加各种稀奇古怪的注释，十分繁琐，突然看到JApiDocs 的介绍，只需要在接口上加上点注释，就能够生成接口文档。突然来了希望，通过看文档自己使用之后，把踩过的坑记录下来

目录

生成的接口文档页面展示：

官方说明文档：

快速使用

导包

添加注释

踩过的坑 

1、官方文档明确说明对所有的controller都要介绍描述注解

这是因为后台接口代码返回的是BaseResult，没有加上泛型

解决方法：修改baseResult，修改泛型就ok了

3、关于参数是否必填坑

总结

JApiDocs 生成父子菜单结构

---

生成的接口文档页面展示：

（示例路径图书接口）

官方说明文档：

JApiDocs Documentation

快速使用

导包

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

最新版本的兼容不添加注解会报错的问题

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

添加注释

执行main函数：(项目根目录是绝对路径)

public class ProductDoc {
    public static void main(String[] args) {
        DocsConfig config = new DocsConfig();
        config.setProjectPath("D:\\xxxx\\src\\main\\java\\com"); // 项目根目录
        config.setProjectName("push_robot_server"); // 项目名称
        config.setApiVersion("V1.0");       // 声明该API的版本
        config.setDocsPath("D:\\doc"); // 生成API 文档所在目录
        config.setAutoGenerate(Boolean.TRUE);  // 配置自动生成
        config.setCodeTplPath("classpath:doc/api-controller.html.ftl");
        Docs.buildHtmlDocs(config); // 执行生成文档
    }
}

踩过的坑 

1、官方文档明确说明对所有的controller都要介绍描述注解

 我开始使用的时候，因为 有几十个controller，所有有几个方法没有加上说明，然后一直报错，我被这个错整懵逼了几个小时，甚至查看了源码，好不容易才明白是少加了注解

使用最新版本1.4.3之后，不加注解也不会报错

信息: info: success to generate docs for controller file : D:\Fj-code\pushing_robot_server\src\main\java\com\fj\controller\app\AppTaskController.java
FreeMarker template error:
The following has evaluated to null or missing:
==> reqNode.description  [in template "api-index.html.ftl" at line 53, column 35]

但是如果根据这个报错，是很难明白到底是哪里少添加了注释的，这个时候，我们查看生成的index.html，用编辑器打开，找到报错的地方，很容易就能够定位少加了注释的是哪个controller

2、生成的接口文档并没有对实体的注释，如下图

而官方文档上面是有实体注释的

这是因为后台接口代码返回的是BaseResult，没有加上泛型

@GetMapping(value = "/getCustomerByPage")
public BaseResult getCustomerByPage

解决方法：修改baseResult，修改泛型就ok了

@GetMapping(value = "/getCustomerByPage")
public BaseResult<CustomerVo> getCustomerByPage

 如果是返回的list，比如列表查询返回的list，需要在泛型加上一个List，如下

@GetMapping(value = "/getCustomerByPage")
public BaseResult<List<CustomerVo>> getCustomerByPage

3、关于参数是否必填坑

如果是必填参数，加上@RequestParam就可以了

@GetMapping(value = "/getCustomerByPage")
public BaseResult<CustomerVo> getCustomerByPage(@RequestParam Integer pageNum,

总结

源码地址：GitHub - YeDaxia/JApiDocs: A magical api documentation generator without annotation for springboot. [No Time Maintain]

官网地址：JApiDocs Documentation

JApiDocs 生成父子菜单结构

JApiDocs 生成父子菜单结构_一点光辉的博客-CSDN博客