JApiDocs是SpringBoot中用来生成接口文档的高效有效的工具，用来帮助开发者快速生成基于注解的RESTFul API接口文档。下面我们就来详细介绍一下如何在Spring Boot项目中整合JApiDocs来生成API接口文档。

准备工作

首先需要创建好一个Spring Boot的项目，并且在POM依赖中引入JApiDocs所需要的依赖配置，如下所示。

<dependency>
    <groupId>io.github.japidocs</groupId>
    <artifactId>springboot-japidocs-starter</artifactId>
    <version>2.3.0</version> <!-- 请根据官网确认最新版本 -->
</dependency>

接下来就是需要在Spring Boot的配置文件中添加JApiDocs的基础信息配置项，如下所示。

japidocs:
  enable: true
  title: 示例 API 文档
  description: 示例项目的 API 文档
  version: 1.0
  base-package: com.example.controller
  server-url: http://localhost:8080
  paths:
    - include: /users/** # 包含路径
    - exclude: /internal/** # 排除路径

使用JApiDocs注解

JApiDocs中通过注解的识别来生成API接口信息，下面我们就来详细介绍一下JApiDocs中的相关注解的使用。

标注接口类和方法

通过在控制器或者是控制器方法上添加对应的API注解来标注API接口信息，用来进行接口文档的生成工作，如下所示。

import io.github.japidocs.annotation.Api;
import io.github.japidocs.annotation.ApiOperation;
import io.github.japidocs.annotation.ApiParam;
import org.springframework.web.bind.annotation.*;

@Api(description = "用户管理接口")
@RestController
@RequestMapping("/users")
public class UserController {

    @ApiOperation("获取用户列表")
    @GetMapping
    public List<User> getUsers() {
        // 示例返回用户列表
        return List.of(new User(1, "Alice"), new User(2, "Bob"));
    }

    @ApiOperation("通过ID获取用户详情")
    @GetMapping("/{id}")
    public User getUserById(
            @ApiParam("用户ID") @PathVariable int id
    ) {
        return new User(id, "Alice");
    }

    @ApiOperation("创建新用户")
    @PostMapping
    public String createUser(
            @ApiParam("用户实体") @RequestBody User user
    ) {
        return "用户创建成功";
    }
}

定义实体类的字段描述

同样我们也可以为实体类来配置相关的注解用来生成实体类字段描述的注解信息，如下所示。

import io.github.japidocs.annotation.ApiModel;
import io.github.japidocs.annotation.ApiModelProperty;

@ApiModel(description = "用户实体类")
public class User {
    @ApiModelProperty("用户ID")
    private int id;

    @ApiModelProperty("用户名")
    private String name;

    // 构造器、Getter 和 Setter
    public User(int id, String name) {
        this.id = id;
        this.name = name;
    }

    // Getters and Setters...
}

运行项目并查看文档

配置完成之后，接下来我们就可以启动Spring Boot项目，通过访问如下的接口来查看生成的接口文档信息。

http://localhost:8080/doc.html

总结

通过上面的步骤，我们就可以在Spring Boot项目中整合JApiDocs，与Swagger类似也是通过注解的方式来配置接口文档生成的描述，通过其强大的功能支持，我们可以生成直接即可文档为前端开发者提供更好的接口文档体验。