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
@ToString
public static class FriendsBean implements Serializable {
private static final long serialVersionUID = 42L;
/**
* 用户id
*/
private String userId;
/**
* 用户名
*/
private String userName;
}
/**
* 读书对象
*/
@Data
@ToString
public 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