Spring Boot整合JApiDocs实现API文档

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

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

接口文档生成器——JApiDocs

下面的步骤是大量照搬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，java培训

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

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;
}

生成的接口描述显示见下