Springboot 无注解文档生成工具 JApiDocs

最新推荐文章于 2024-07-25 06:15:00 发布

吻碟的痕

最新推荐文章于 2024-07-25 06:15:00 发布

阅读量706

点赞数 1

本文链接：https://blog.csdn.net/qq_27535933/article/details/123547180

版权

介绍：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，本文用在线工具进行转换截图如下：