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

被写接口文档难受了好久，突然看到JApiDocs 的介绍，突然来了希望，通过看文档自己使用之后，把踩过的坑记录下来

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

（示例路径http://oss.agilestudio.cn/apidocs/V2.0/controller_BookController.html#getBookDetail）

官方说明文档：

https://japidocs.agilestudio.cn/#/zh-cn/?id=apidoc

快速使用

导包

<dependency>
  <groupId>io.github.yedaxia</groupId>
  <artifactId>japidocs</artifactId>
  <version>1.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，所有有几个方法没有加上说明，然后一直报错，我被这个错整懵逼了几个小时，甚至查看了源码，好不容易才明白是少加了注解

信息: 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

3、关于参数是否必填坑

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

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

总结

源码地址：https://github.com/YeDaxia/JApiDocs

官网地址：https://japidocs.agilestudio.cn/#/zh-cn/?id=apidoc