`javafree-cloud-springdoc` 开发与使用说明

版本：2.0.1 适用框架：Spring Boot 3.x + SpringDoc OpenAPI 2.x（兼容 Jakarta EE 9+）
最后更新：2025年12月
代码参见: https://gitee.com/javafree-cloud/javafree2025-examples

📦 一、工具包简介

javafree-cloud-springdoc 是一个基于 Spring Boot Starter 机制 封装的 Swagger/OpenAPI 自动配置工具包，旨在为 JavaFree Cloud 微服务架构提供 开箱即用、高度可配置、支持多分组文档管理 的 API 文档能力。

它在官方 springdoc-openapi-starter-webmvc-ui 基础上，封装了以下企业级功能：

✅ 全局 OpenAPI 元信息统一配置（标题、版本、联系人、许可证等）
✅ JWT Bearer 安全认证自动集成
✅ 多环境服务器地址切换（开发/测试/生产）
✅ 支持多分组 API 文档（按业务模块隔离接口）
✅ 灵活的路径匹配与排除规则
✅ 完全通过 application.yml 配置驱动，零代码侵入
✅ 向后兼容单分组模式，平滑升级

🧩 二、核心价值

价值点	说明
标准化	统一所有微服务的 API 文档风格、安全策略、元信息格式
提效	开发者无需重复编写 `@OpenAPIDefinition` 或 `GroupedOpenApi` Bean
灵活性	支持单分组（快速启动）和多分组（复杂系统）两种模式
安全性	内置 JWT Bearer 方案，一键开启 Authorization 头
可维护性	所有配置集中管理，支持动态调整扫描范围
低耦合	仅需引入依赖 + 配置，无任何业务代码侵入

🚀 三、快速开始（Spring Boot 工程使用示例）

步骤 1：添加 Maven 依赖

在你的 Spring Boot 项目 pom.xml 中添加：

xml

<dependency>
    <groupId>cn.javafree.cloud</groupId>
    <artifactId>javafree-cloud-springdoc</artifactId>
    <version>2.0.1</version>
</dependency>

💡 确保你的项目已引入 spring-boot-starter-web（Web 应用必需）

步骤 2：配置 `application.yml`

示例 1：基础单分组模式（适合小型项目）

yaml

javafree:
  springdoc:
    enabled: true
    title: 我的订单服务 API
    version: 1.2.0
    description: 订单创建、查询、取消等接口
    contact:
      name: 订单团队
      email: order-team@javafree.cn
    jwt-security: true
    servers:
      - url: http://localhost:8080
        description: 本地开发
      - url: https://order.api.javafree.cn
        description: 生产环境

访问：http://localhost:8080/swagger-ui.html 即可查看文档。

示例 2：多分组模式（推荐用于中大型系统）

yaml

javafree:
  springdoc:
    title: 用户中心 API
    version: 2.0.1
    jwt-security: true
    servers:
      - url: http://localhost:8080
        description: 开发环境
    group-configs:
      - group: "AI 模型管理"
        packages-to-scan:
          - cn.javafree.cloud.ai
        paths-to-match:
          - /ai/**

      - group: "日志管理"
        packages-to-scan:
          - cn.javafree.cloud.accesslog
        paths-to-match:
          - /access_log/**

      - group: "系统管理"
        packages-to-scan:
          - cn.javafree.cloud.restful.controller
        paths-to-match:
          - /**
        paths-to-exclude:
          - /sys/internal/**

      - group: "全部接口"
        packages-to-scan:
          - cn.javafree.cloud
        paths-to-match:
          - /**

效果：

Swagger UI 顶部出现分组下拉框
可分别查看“系统管理”、“日志管理”等独立文档
/auth/internal/** 路径在“权限管理”分组中被隐藏

示例图：

API分组

步骤 3（可选）：关闭文档（如生产环境）

yaml

javafree:
  springdoc:
    enabled: false  # 完全禁用 Swagger UI 和 /v3/api-docs

⚠️ 建议在生产环境通过配置中心动态关闭，提升安全性。

🔍 四、接口与模型如何被 SpringDoc 扫描并生成文档

本工具包基于 SpringDoc OpenAPI 实现，其核心机制是：

自动扫描所有被 @RestController 或 @Controller 注解的类
识别其中带有 HTTP 方法注解（如 @GetMapping, @PostMapping 等）的方法
通过 JSR-303 / Jakarta Bean Validation 和 @Schema 注解解析 DTO 字段语义
结合 @Tag, @Operation, @Parameter, @ApiResponse 等 OpenAPI 注解生成结构化文档

你无需额外配置即可让接口和模型出现在 Swagger UI 中，前提是：

Controller 类在 Spring 扫描路径内（通常由 @SpringBootApplication 的 scanBasePackages 控制）
模型类（DTO/VO）被接口方法的参数或返回值引用
使用了 OpenAPI 标准注解（推荐）或依赖字段名/类型推断（基础支持）

✅ 接口文档生成原理示例解析

以 AccessLogController 为例：

java

@RestController
@RequestMapping("/access_log")
@Tag(name = "日志管理控制器", description = "提供日志管理的查询和删除操作接口")
public class AccessLogController {
    // ...
}

扫描逻辑说明：

元素	作用	是否必需
`@RestController`	标记为 Web 控制器，会被 SpringDoc 扫描	✅ 必需
`@RequestMapping("/access_log")`	定义基础路径，所有方法路径基于此	✅ 推荐
`@Tag`	定义该 Controller 在 Swagger UI 中所属的“标签组”	❌ 可选（默认用类名）
`@Operation`	描述单个 API 的摘要和详细说明	❌ 可选（但强烈建议）
`@RequestParam` / `@RequestBody`	告知 SpringDoc 参数来源（Query / Body）	✅ 必需（否则无法识别参数）

💡 即使不写 @Tag 和 @Operation，SpringDoc 也会根据方法名、参数类型自动生成基础文档，但缺乏业务语义。

✅ 模型（DTO）文档生成原理

以 AccessLogDTO 为例：

java

@Data
@Schema(description = "访问日志 DTO，表示用户访问系统的操作记录")
public class AccessLogDTO implements Serializable {

    @Schema(description = "唯一ID (UUID)", example = "550e8400-e29b-41d4-a716-446655440000")
    private String id;

    @Schema(description = "请求开始时间", example = "2025-07-07 10:00:00")
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "Asia/Shanghai")
    private LocalDateTime requestTime;
    
    // ...
}

模型解析逻辑：

注解/特性	作用
`@Schema`	定义字段在 OpenAPI 文档中的描述、示例值、是否必填等
`example = "..."`	在 Swagger UI 的“Example Value”中显示示例，极大提升可读性
`@JsonFormat`	SpringDoc 会结合它推断时间格式，在 Schema 中显示为 `string (date-time)`
Lombok `@Data`	自动生成 getter/setter，SpringDoc 通过反射读取字段，不影响文档生成
`@JsonIgnoreProperties(ignoreUnknown = true)`	仅影响 JSON 反序列化，不影响文档展示

✅ 关键点：只要你的 DTO 被用作：
@RequestBody 的泛型类型（如 ApiParamBody<AccessLogDTO>）
返回值泛型（如 ApiResponse<PageResult<AccessLogDTO>>）
SpringDoc 就会递归解析整个对象树，包括嵌套对象、集合、泛型等。

⚙️ 五、完整配置项说明

配置项	类型	默认值	说明
`enabled`	boolean	`true`	是否启用文档功能
`title`	string	`"JavaFree Cloud API"`	文档标题
`version`	string	`"2.0.1"`	API 版本
`description`	string	`"由 javafree-cloud-springdoc 生成"`	描述（支持 Markdown）
`license.name`	string	`"JavaFreeCloud 授权协议"`	许可证名称
`license.url`	string	`"http://www.javafree.cn/license.html"`	许可证链接
`contact.name`	string	技术支持信息	联系人
`servers`	List	localhost + production	多环境服务器列表
`jwt-security`	boolean	`true`	是否启用 Bearer Token 安全方案
`vendor-extension`	string	`"JavaFreeCloud"`	自定义扩展字段（写入 OpenAPI info）

多分组专用配置（`group-configs`）

子项	类型	必填	说明
`group`	string	是	分组名称（显示在 UI 下拉框）
`packages-to-scan`	string[]	否	扫描的 Controller 包路径
`paths-to-match`	string[]	否	包含的路径（Ant 风格，如 `/user/**`）
`paths-to-exclude`	string[]	否	排除的路径（优先级更高）

🔔 注意：只要配置了 group-configs，系统将忽略顶层的 group、packages-to-scan 等单分组字段。

🛠️ 六、开发者最佳实践建议

1. Controller 层

使用 @Tag 明确业务模块归属
每个接口必须加 @Operation(summary = "...")，避免方法名暴露技术细节
复杂参数建议封装为 DTO，不要直接用 Map 或 Object

2. DTO/VO 层

每个字段都加 @Schema，至少包含 description
强烈建议提供 example，尤其对时间、ID、枚举等字段
敏感字段（如密码、token）应使用 @Schema(accessMode = READ_ONLY) 或 @JsonIgnore（但注意：@JsonIgnore 会完全隐藏字段，慎用）

3. 返回值统一包装

如你使用的 ApiResponse<T>，确保其泛型能被正确解析
可在 ApiResponse 类上加全局 @Schema 提升可读性：

java

@Schema(description = "通用 API 响应结构")
public class ApiResponse<T> {
    @Schema(description = "状态码，200=成功", example = "200")
    private int code;
    
    @Schema(description = "业务消息", example = "操作成功")
    private String message;
    
    @Schema(description = "响应数据体")
    private T data;
}

📦 七、工具包如何增强这一过程？

javafree-cloud-springdoc 并不改变 SpringDoc 的扫描机制，而是：

预配置 OpenAPI 元信息（标题、联系人、服务器等），避免每个项目重复写
自动注册 JWT 安全方案，使所有接口在 Swagger UI 中支持 “Authorize” 输入 Token
通过 group-configs 实现按包/路径分组，即使多个 Controller 使用相同 @Tag，也能隔离展示
提供统一开关（enabled），一键关闭文档（生产环境安全）

🌟 你的代码只需关注业务注解（@Tag, @Operation, @Schema），其余交给 Starter！

🛡️ 八、安全建议

生产环境务必关闭文档：
yaml
```
javafree.springdoc.enabled: false
```
若需保留，应配合 网关鉴权 或 IP 白名单 限制访问 /swagger-ui.html 和 /v3/api-docs
jwt-security: true 仅用于文档测试，不影响实际接口安全逻辑

📚 九、常见问题

Q1：为什么配置了 `group-configs` 但 Swagger UI 没有分组下拉框？

A：请确认是否引入了 springdoc-openapi-starter-webmvc-ui（本 Starter 已包含），且未手动禁用 UI。

Q2：如何排除某些 Controller 不生成文档？

A：使用 paths-to-exclude 或不在 packages-to-scan 中包含其包路径。

Q3：能否同时使用 Spring Security？

A：可以。本工具包只负责文档生成，安全由 Spring Security 控制。建议对 /swagger-ui.html 和 /v3/api-docs 添加权限控制。

✅ 十、总结：为什么选择 `javafree-cloud-springdoc`？

对比项	原生 SpringDoc	`javafree-cloud-springdoc`
配置复杂度	高（需手动写 OpenAPI Bean）	极低（YAML 驱动）
多分组支持	需编码 `GroupedOpenApi`	YAML 配置 `group-configs`
安全集成	需手动配置 SecurityScheme	`jwt-security: true` 一键开启
团队规范	依赖开发者自觉	强制统一元信息、风格
生产安全	需手

javafree-cloud-springdoc 开发与使用说明 ​

📦 一、工具包简介 ​

🧩 二、核心价值 ​

🚀 三、快速开始（Spring Boot 工程使用示例） ​

步骤 1：添加 Maven 依赖 ​

步骤 2：配置 application.yml ​

示例 1：基础单分组模式（适合小型项目） ​

示例 2：多分组模式（推荐用于中大型系统） ​

步骤 3（可选）：关闭文档（如生产环境） ​

🔍 四、接口与模型如何被 SpringDoc 扫描并生成文档 ​

✅ 接口文档生成原理示例解析 ​

扫描逻辑说明： ​

✅ 模型（DTO）文档生成原理 ​

模型解析逻辑： ​

⚙️ 五、完整配置项说明 ​

多分组专用配置（group-configs） ​

🛠️ 六、开发者最佳实践建议 ​

1. Controller 层 ​

2. DTO/VO 层 ​

3. 返回值统一包装 ​

📦 七、工具包如何增强这一过程？ ​

🛡️ 八、安全建议 ​

📚 九、常见问题 ​

Q1：为什么配置了 group-configs 但 Swagger UI 没有分组下拉框？ ​

Q2：如何排除某些 Controller 不生成文档？ ​

Q3：能否同时使用 Spring Security？ ​

✅ 十、总结：为什么选择 javafree-cloud-springdoc？ ​

`javafree-cloud-springdoc` 开发与使用说明

📦 一、工具包简介

🧩 二、核心价值

🚀 三、快速开始（Spring Boot 工程使用示例）

步骤 1：添加 Maven 依赖

步骤 2：配置 `application.yml`

示例 1：基础单分组模式（适合小型项目）

示例 2：多分组模式（推荐用于中大型系统）

步骤 3（可选）：关闭文档（如生产环境）

🔍 四、接口与模型如何被 SpringDoc 扫描并生成文档

✅ 接口文档生成原理示例解析

扫描逻辑说明：

✅ 模型（DTO）文档生成原理

模型解析逻辑：

⚙️ 五、完整配置项说明

多分组专用配置（`group-configs`）

🛠️ 六、开发者最佳实践建议

1. Controller 层

2. DTO/VO 层

3. 返回值统一包装

📦 七、工具包如何增强这一过程？

🛡️ 八、安全建议

📚 九、常见问题

Q1：为什么配置了 `group-configs` 但 Swagger UI 没有分组下拉框？

Q2：如何排除某些 Controller 不生成文档？

Q3：能否同时使用 Spring Security？

✅ 十、总结：为什么选择 `javafree-cloud-springdoc`？