使用JApiDocs插件自动生成API接口文档，巨好用！

话不多说，直接上干货，介绍如何使用它。

---

一、生成的接口文档页面展示

markdown文档格式：

html网页格式：

---

二、官方说明文档：

JApiDocs官方文档

1.导包

代码如下（示例）：

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

2.在项目根目录下创建名为markdownio.github.yedaxia.apidocs.plugin.markdown的包名，并将MarkdownDocPlugin文件复制到该包下

3.将api-doc.md.ftl文件复制到resources根目录下

2、3步骤如下图所示：

4.添加必要的注释

5.在项目启动类同目录下创建TestJApiDocs类，复制以下代码到TestJApiDocs类中（配置参数可以自定义）

public static void main(String[] args) {
     // 1. 创建生成文档的配置
     DocsConfig config = new DocsConfig();
     config.setProjectPath("D:\\xx-project\\projectName");// 项目所在目录
     config.setDocsPath("D:\\api");          // 生成 HTML 接口文档的目标目录
     config.setAutoGenerate(false);                           // 是否给所有 Controller 生成接口文档
     config.setProjectName("projectName");                 // 项目名
     config.setApiVersion("V1.0");                           // API 版本号
     // 使用 MD 插件，额外生成 MD 格式的接口文档，两个入参可以修改成自己实际的场景
     config.addPlugin(new MarkdownDocPlugin("测试","http://192.168.x.x:8080/projectName"));
     // 2. 执行生成 HTML 接口文档
     Docs.buildHtmlDocs(config);
}

6.执行该main方法，就可以生成html与markdown格式的api接口文档啦

四、采坑及注意事项

1、JApiDocs响应结果的采坑总结

1. 我们知道，如果Controller声明了@RestController，SpringBoot会把返回的对象直接序列成Json数据格式返回给前端。 JApiDocs也利用了这一特性来解析接口返回的结果，但由于JApiDocs是静态解析源码的，因此你要明确指出返回对象的类型信息，JApiDocs支持继承、泛型、循环嵌套等复杂的类解析。

2. JApiDocs 是基于源码文件进行解析的，而且只对 JavaBean的成员变量进行了遍历，对于动态设置的内容，比如 map 里面的内容是没法解析到的。

2、使用注意事项

1. @ApiDoc注解可以作用在类或者方法上，作用在类上时，整个类中的所有接口方法都会被生成文档，作用在方法上时，只有当前接口方法会生成文档。
2. 可以自己修改api-doc.md.ftl文件，来生成自定义格式的API接口markdown文档。
3. 可以自己修改MarkdownDocPlugin类实体，添加自己需要添加的属性变量，这些属性变量可以在api-doc.md.ftl文件中使用。
4. @Ignore注解的使用，它能够在生成文档时忽略生成。当它作用在类上时，会忽略整个类；当它作用在接口方法上，会忽略该方法；当它作用在方法的属性时，会忽略该属性字段。

---

总结及分享

文章中需要的类文件资源：
链接: https://pan.baidu.com/s/1OUauquBRJ2Ohr0PiurM4iQ 提取码: sep3
对文章步骤有疑问的朋友可以留言，博主看到就会回复