介绍:JApiDocs 是springboot一个无注解的Api文档生成器。
由于很多Springboot项目并没有用到swagger或Knife4j,导致编写开发文档比较痛苦,本文结合自身的经历,推荐JApiDocs的工具使用。
环境: java8、Springboot 2.6.4、Gradle 7.4.1、JApiDocs1.4.1
JApiDocs官网地址:JApiDocs Documentation
JApiDocs开源地址:https://github.com/YeDaxia/JApiDocs
搭建:
1. Gradle引入
plugins {
id 'org.springframework.boot' version '2.6.4'
id 'io.spring.dependency-management' version '1.0.11.RELEASE'
id 'java'
}
group = 'com.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '1.8'
repositories {
mavenCentral()
}
dependencies {
implementation 'org.springframework.boot:spring-boot-starter-web'
implementation('org.springframework.boot:spring-boot-starter-validation')
implementation 'io.github.yedaxia:japidocs:1.4.4'
testImplementation 'org.springframework.boot:spring-boot-starter-test'
}
tasks.named('test') {
useJUnitPlatform()
}
2. 配置 (注:简化配置 可以写成bean形式 也可以改写为调用接口 或者main方法 test单元测试)
package com.example;
import io.github.yedaxia.apidocs.Docs;
import io.github.yedaxia.apidocs.DocsConfig;
import io.github.yedaxia.apidocs.plugin.markdown.MarkdownDocPlugin;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class Demo1Application {
public static void main(String[] args) {
DocsConfig config = new DocsConfig();
config.setProjectPath("/Users/Documents/work/my-tool/swagger-doc/demo-1"); // 项目根目录
config.setProjectName("demo-1"); // 项目名称
config.setApiVersion("V1.0"); // 声明该API的版本
config.setDocsPath("/Users/Documents/work/my-tool/swagger-doc/demo-1/data"); // 生成API 文档所在目录
config.setAutoGenerate(Boolean.TRUE); // 配置自动生成
config.addPlugin(new MarkdownDocPlugin()); // 生成MarkDown
Docs.buildHtmlDocs(config); // 执行生成文档
SpringApplication.run(Demo1Application.class, args);
}
}
3. controller 测试
package com.example.controller;
import com.example.service.form.UserForm;
import com.example.service.form.UserListForm;
import com.example.service.result.ApiResult;
import com.example.service.result.PageResult;
import com.example.service.result.user.UserVO;
import org.springframework.web.bind.annotation.*;
/**
* 用户接口
*/
@RequestMapping("/api/user/")
@RestController
public class UserController {
/**
* 用户列表
* @param listForm
*/
@RequestMapping(path = "list", method = {RequestMethod.GET, RequestMethod.POST} )
public ApiResult<PageResult<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;
}
}
4.测试中用到的DTO(注:整合到一起了。 自行分解)
public class UserVO extends SimpleUser {
@RapMock(limit = "1-10")
private SimpleUser[] friends; //好友
private Boolean isFollow; //是否关注
private List<UserVO> follower;
public SimpleUser[] getFriends() {
return friends;
}
public void setFriends(UserVO[] friends) {
this.friends = friends;
}
public Boolean getFollow() {
return isFollow;
}
public void setFollow(Boolean follow) {
isFollow = follow;
}
public void setFriends(SimpleUser[] friends) {
this.friends = friends;
}
}
package com.example.service.result.user;
import io.github.yedaxia.apidocs.Ignore;
import io.github.yedaxia.apidocs.RapMock;
import java.io.Serializable;
public class SimpleUser implements Serializable {
@RapMock(value="@ID")
private String userId; //用户id
@RapMock("@NAME")
private String userName; //用户名
@Ignore
private String ignore; //忽略字段
private SimpleUser friend;
public SimpleUser getFriend() {
return friend;
}
public void setFriend(SimpleUser friend) {
this.friend = friend;
}
public String getIgnore() {
return ignore;
}
public void setIgnore(String ignore) {
this.ignore = ignore;
}
public String getUserId() {
return userId;
}
public void setUserId(String userId) {
this.userId = userId;
}
public String getUserName() {
return userName;
}
public void setUserName(String userName) {
this.userName = userName;
}
}
package com.example.service.result;
import java.io.Serializable;
public class ApiResult<T extends Serializable> extends BaseResult<T>{
private Integer code;
private String errMsg;
private T data;
private Type errType;
/**
* 状态类型
*/
public enum Type
{
/** 成功 */
SUCCESS(0),
/** 警告 */
WARN(301),
/** 错误 */
ERROR(500);
private final int value;
Type(int value)
{
this.value = value;
}
public int value()
{
return this.value;
}
}
}
package com.example.service.result;
import java.io.Serializable;
public class BaseResult<T extends Serializable> implements Serializable {
private T body;
}
package com.example.service.result;
import java.io.Serializable;
import java.util.List;
public class PageResult<T> implements Serializable {
private Integer total; //总记录数
private Integer pageCount; //页数
private Integer currentPage; //当前页
private Integer pageSize; //每页记录数
private List<T> list; //列表数据
private Boolean hasMore; //是否还有更多
}
5. 启动项目以后文件会生成在配置的路径。
通过工具可以将MarkDown文件转换成word或者pdf,本文用在线工具进行转换截图如下:
本文简介了一下使用方式,根据文档的内容还可以进行扩展,有需要的小伙伴可以尝试了解。
已将demo上传,没有积分下方评论下留下邮箱地址看到后会及时回复,感谢各位
资源地址:Springboot无注解文档生成工具JApiDocs-Java文档类资源-CSDN下载