JApiDocs介绍

JApiDocs功能与swagger类似，JApiDocs能生成各种格式的文档包括主要html，Markdown等等，它还支持你自定义自己的文档格式，你可以通过添加自己的插件添加自己自定义的文档格式。

swagger的缺点

swagger的优点就不说了，大家可以自行百度，用过swagger的人都知道，用swagger要在各个相应的类上，属性上，或者controller的请求方法上加上大量的注解，特别是实体的属性特别多的时候，这就很烦人了。

JApiDocs与Swagger的优势

首先，JApiDocs不需要写大量的注解，除非一些特别的声明，还是swagger的文档目前好像只有html格式（这个不太清楚)，但是JApiDocs能生成各种格式的文档包括主要html，Markdown等等，还支持自定义插件添加你自定义的文档格式。

JApiDocs的中文官方文档地址

https://japidocs.agilestudio.cn/#/zh-cn/?id=%e5%85%a5%e9%97%a8

JApiDocs的简单使用示例

（1）导入相关jar包

        <!-- JApiDocs依赖--><dependency><groupId>io.github.yedaxia</groupId><artifactId>japidocs</artifactId><version>1.4</version></dependency><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><version>1.18.12</version></dependency>

（2）写上JApiDocs的相应参数

        DocsConfig config = new DocsConfig();config.setProjectPath("D:\\idea\\document_demo"); // 项目根目录config.setProjectName("DemoDocument"); // 项目名称config.setApiVersion("V1.0");       // 声明该API的版本config.setDocsPath("D:\\idea\\document_demo\\docs"); // 生成API 文档所在目录config.setAutoGenerate(Boolean.TRUE);  // 配置自动生成// 导出markdown 的插件config.addPlugin(new MarkdownDocPlugin());Docs.buildHtmlDocs(config); // 执行生成文档

不添加插件默认只导出html格式，上面为了演示我多导出MarkDowm格式的，上面这段代码你可以加在项目里任何一个main方法里，如我这里就随便写了一个类的main方法

（3）写好你的controller和相应的实体类，基本上不需要像swagger那样写一大堆注解，这样就ok了
controller代码：

package com.document.documentdemo.controller;import com.document.documentdemo.entity.ApiResult;
import com.document.documentdemo.entity.UserForm;
import com.document.documentdemo.entity.UserListForm;
import com.document.documentdemo.entity.UserVO;
import org.springframework.web.bind.annotation.*;import java.util.List;/*** @author chenxq* @site www.daxiong.com* @company daxiong有限公司* @create 2020-07-10 9:52*/
@RequestMapping("/api/demo/")
@RestController
public class DemoController {/*** 用户列表* @param listForm*/@RequestMapping(path = "list", method = {RequestMethod.GET,  RequestMethod.POST}  )public ApiResult<List<UserVO>> list(UserListForm listForm){return null;}/*** 保存用户* @param userForm*/@PostMapping(path = "save")public ApiResult<UserVO> saveUser(@RequestBody UserForm userForm){return null;}/*** 删除用户* @param userId 用户ID*/@PostMapping("delete")public ApiResult deleteUser(@RequestParam Long userId){return null;}
}

一些实体的代码：
这里我只贴一个UserVO实体

package com.document.documentdemo.entity;import lombok.Data;
import lombok.ToString;import java.io.Serializable;
import java.util.List;/*** 用户对象返回实体* @author chenxq* @site www.daxiong.com* @company daxiong有限公司* @create 2020-07-10 10:04*/
@Data
@ToString
public class UserVO implements Serializable {private static final long serialVersionUID = 42L;/*** 用户id*/private String userId;/*** 用户名*/private String userName;/*** 是否关注*/private String isFollow;/*** 朋友列表*/private List<FriendsBean> friends;/*** 书籍列表*/private List<ReadBooksBean> readBooks;/*** 朋友对象*/@Data@ToStringpublic static class FriendsBean implements Serializable {private static final long serialVersionUID = 42L;/*** 用户id*/private String userId;/*** 用户名*/private String userName;}/*** 读书对象*/@Data@ToStringpublic static class ReadBooksBean implements Serializable {private static final long serialVersionUID = 42L;/*** 图书id*/private String bookId;/*** 图书名称*/private String bookName;}
}

（4）运行一些配置JApiDocs的main方法就可以生成文档了

成功后项目下指定目录会有文档生成

文档里有个小问题，如果返回的对象有嵌套对象，文档不会展示嵌套对象的内容

这里只是简单展示使用，想深入学习得去官网：

https://japidocs.agilestudio.cn/#/zh-cn/?id=%e5%85%a5%e9%97%a8