接口文档

说明

说明

• 由于 springfox 与 knife4j 均停止维护 bug众多
• 选用 springdoc 框架
• 基于 javadoc 无注解零入侵生成规范的 openapi 结构体
• 由于框架自带文档UI功能单一扩展性差 故移除自带UI 建议使用外置文档工具

系统接口文档规范

• OpenAPI 3.0 规范 + SpringDoc
• 常用核心注解

//类
@Tag(name = "用户管理", description = "用户注册、登录、信息管理")

//方法
@Operation(summary = "创建用户", description = "通过用户名和密码注册新用户")

• 默认文档地址 swagger-ui

升级文档工具

• 由于框架采用 openapi 行业规范 故市面上大部分的框架均支持 可自行选择
• 例如: apifox apipost postman torna knife4j 等 根据对应工具的文档接入即可

官网连接: https://www.apifox.cn/

• 推荐下载客户端软件
• 注册/登录软件后进行下面操作

方式一（推荐）

TIP

• 优点：灵活对某一个类进行提交更新接口
• 缺点：非自动

Api Fox文档

Apifox IDEA 插件快速上手

配置 API 访问令牌

同步接口

• IDEA 安装插件

• 获取 Token

• 测试链接

• 上传到 ApiFox

• 效果

方式二

TIP

• 优点：利用 Apifox 的导入工具，可以自动定时获取数据
• 缺点：自动刷新周期过长，不能实时刷新

• 根据项目内所有文档组完成所有数据源创建(拉取后端openapi结构体)
• 数据源URL格式 http://后端ip:端口/v3/api-docs/组名

示例：数据源URL格式
http://localhost:8080/v3/api-docs/1.系统模块

http://localhost:8080/v3/api-docs/9.演示模块


也可不分组统一导入
http://localhost:8080/v3/api-docs

操作如下图：

分享文档

• 创建分享

  

• 预览文档

Springdoc 常用注解

注解	作用	扩展
@Tag(name = "分组名")	API 分组类注解	定义接口模块分组，作用于类或方法。Springdoc 的 @Tag 更灵活，支持 description 字段。
@Operation(summary = "摘要")	接口方法描述	描述单个接口的作用。Springdoc 的 @Operation 支持更多字段，如 tags、hidden 等。
@Parameter(description = "参数说明")	参数描述	描述方法参数。Springdoc 的 @Parameter 支持 required、example 等更细粒度配置。
@Schema(description = "字段说明")	模型字段描述	描述 DTO 或模型的字段。@Schema 支持 example、nullable 等扩展属性。
@ApiResponse(responseCode = "200", description = "成功")	响应结构定义	定义接口返回的 HTTP 状态码和描述。Springdoc 使用 responseCode 替代 code。
@SecurityScheme + @SecurityRequirement	全局安全配置	Springdoc 通过 @SecurityScheme 定义安全方案（如 OAuth2、JWT），并在接口上使用 @SecurityRequirement 绑定。

详细注解使用示例

1. API 分组与接口描述

// Springdoc
@RestController
@Tag(name = "用户模块", description = "用户注册、登录、查询等操作")
public class UserController {

    @Operation(
        summary = "获取用户信息",
        description = "根据用户ID查询详细信息",
        tags = {"查询类接口"}
    )
    @GetMapping("/users/{id}")
    public User getUser(@Parameter(description = "用户ID", example = "1001") @PathVariable Long id) {
        // ...
    }
}

2. 模型字段描述

// Springdoc
public class User {
    @Schema(description = "用户ID", example = "1001", requiredMode = Schema.RequiredMode.REQUIRED)
    private Long id;

    @Schema(description = "用户名", example = "john_doe", maxLength = 20)
    private String username;
}

3. 安全认证配置

// Springdoc
@Configuration
@SecurityScheme(
    name = "BearerAuth",
    type = SecuritySchemeType.HTTP,
    scheme = "bearer",
    bearerFormat = "JWT"
)
public class OpenApiConfig {}

@Operation(summary = "删除用户", security = @SecurityRequirement(name = "BearerAuth"))
@DeleteMapping("/users/{id}")
public void deleteUser(@PathVariable Long id) {
    // ...
}