Spring Boot整合JApiDocs实现API文档

对Swagger相当不爽的两点，一是要大量写各种注解，二是很被诟病的一点，对返回对象的描述相当不人性化（虽然可以写代码来实现，但不爽）。

在大部分时候，我们其实只关注接口的4个方面： 接口功能描述、接口URL、提交参数说明、返回结果说明。
JApiDocs完美的满足上面的基本要求，见下图：

接口文档生成器——JApiDocs，JApiDocs官网教程相当棒：https://japidocs.agilestudio.cn/#/zh-cn/

下面的步骤是大量照搬JApiDocs官网的内容。

第一步：添加依赖

通过IDEA创建Spring Boot，在创建工程时，可以把web依赖勾选上（不勾选也没关系，后面在pom.xml中再添加也行）。

<dependency> 
    <groupId>io.github.yedaxia</groupId> 
    <artifactId>japidocs</artifactId> 
    <version>1.4.4</version> 
</dependency>

第二步：配置参数

在任意一个main入口运行下面的代码，我是直接写在Spring Boot的启动类中的，如下：

package com.jcj.japidemo;
import io.github.yedaxia.apidocs.Docs;
import io.github.yedaxia.apidocs.DocsConfig;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class JapidemoApplication
{
    public static void main(String[] args)
    {
        SpringApplication.run(JapidemoApplication.class, args);

        //JApiDocs 配置参数
        DocsConfig config = new DocsConfig();
        config.setProjectPath("C:\\IdeaProjects\\japidemo"); // 项目根目录
        config.setProjectName("japidemo"); // 项目名称
        config.setApiVersion("V1.0");       // 声明该API的版本
        config.setDocsPath("C:\\IdeaProjects\\japidemo\\apidoc"); // 生成API 文档所在目录
        config.setAutoGenerate(Boolean.TRUE);  // 配置自动生成
        Docs.buildHtmlDocs(config); // 执行生成文档
    }
}

所有的工作就做完了！相当Easy

在编码时，你只需注意编码规范，，顺手写好必要的注释就行了，那么接口文档就能自动生成，不用加任何注解。

1. 类上加注释（不是注解）

“用户接口”注释会显示为左侧树形目录的根目录

/**
 * 用户接口
 * @Auther: 江成军
 * @Date: 2021/8/22 22:16
 */
@RestController
@RequestMapping(value="/apiuser")
public class UserController
{
	...
}

2. 方法上加注释（不是注解）

"用户接口"会显示为左侧导航树的目录，@description会显示为副标题，每一个参数对应一个@param

/**
    * 用户详情(RESTFul方式)
    * @description 根据姓名，年龄查询用户详情，url中只需传值
    * @param name 姓名
    * @param age 年龄
    * @Author 江成军
    * @Date 2021/8/22 23:32
    **/
    @GetMapping(value="/users/{name}/{age}")
    public Result<User> userDetail2(@PathVariable String name, @PathVariable int age)
    {
        System.out.println(name+","+age);

        Result result=new Result();
        User u1=new User();
        u1.setName("张三");
        u1.setAge(23);
        u1.setWeight(122.6f);

        result.setCode(200);
        result.setMessage("更新成功");
        result.setData(u1);

        return result;
    }

生成的接口描述显示见下图:

3. 实体类上加注释（不是注解）

直接在属性上面加注释就行了，用//或者*注释都行，我比较喜欢用//，见下图：


这样在返回结果上面，直接就会清楚明了的显示:

WEB项目开发中碰到的问题千奇百怪，大家想了解对如何快速的掌握Spring Boot，可以参见视频：

51CTO：Spring Boot+Bootstrap开发小而完整web项目
腾讯课堂：Spring Boot+Bootstrap开发小而完整web项目
CSDN学院：Spring Boot+Bootstrap开发小而完整web项目
网易云课堂：Spring Boot+Bootstrap开发小而完整web项目