JApiDocs将会是一个比Swagger更好的java文档

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