1. 包声明与导入

package com.example.mqttbroker.config;  // 配置类所在包路径

import io.swagger.v3.oas.models.*;      // OpenAPI 核心模型
import io.swagger.v3.oas.models.info.*; // API 元数据信息类
import org.springdoc.core.models.GroupedOpenApi;  // SpringDoc 分组配置
import org.springframework.context.annotation.*; // Spring 配置注解

• 功能：声明配置类位置，导入 OpenAPI 和 SpringDoc 所需的依赖。

2. 配置类声明

@Configuration  // 标记为 Spring 配置类
public class OpenApiConfig { ... }

• 功能：定义 Spring Boot 配置类，用于集中管理 OpenAPI 文档配置。

3. 全局 OpenAPI 配置

@Bean
public OpenAPI brokerOpenAPI() {
    return new OpenAPI()
        .info(new Info()
            .title("MQTT Broker 管理 API")         // API 标题
            .version("v1.0.0")                     // 版本号
            .description("基于 Moquette 0.17 的嵌入式 MQTT Broker...") // 详细描述
            .contact(new Contact()
                .name("你的名字")                   // 维护者姓名
                .email("you@example.com"))         // 联系邮箱
            .license(new License()
                .name("Apache 2.0")))             // 许可证类型
        .externalDocs(new ExternalDocumentation()
            .description("项目主页/README")          // 外部文档描述
            .url("https://your.repo.url"));        // 文档链接
}

• 功能：
  • 定义 API 全局元数据：标题、版本、描述、联系人和许可证。
  • 添加外部文档链接（如项目主页或 README）。
• 作用：生成 Swagger UI 页面的头部信息。

4. API 分组配置 (Broker 管理接口)

@Bean
public GroupedOpenApi adminApi() {
    return GroupedOpenApi.builder()
        .group("admin")          // 分组名称（显示在 Swagger UI 下拉菜单）
        .pathsToMatch("/api/**") // 匹配以 `/api/` 开头的所有路径
        .build();
}

• 功能：
  • 创建名为 admin 的分组。
  • 包含所有路径为 /api/** 的接口（例如 /api/status、/api/config）。
• 作用：在 Swagger UI 中按模块分类接口，便于管理。

5. API 分组配置 (ACL 管理接口)

@Bean
public GroupedOpenApi aclApi() {
    return GroupedOpenApi.builder()
        .group("acl")               // 分组名称
        .pathsToMatch("/api/acl/**") // 匹配 ACL 相关路径
        .build();
}

• 功能：
  • 创建名为 acl 的分组。
  • 仅包含路径为 /api/acl/** 的接口（如 /api/acl/add）。
• 作用：隔离访问控制列表（ACL）相关接口，实现精细化管理。

核心功能总结

使用示例

访问 Swagger UI 后：

1. 顶部显示全局信息（标题、版本、许可证）。
2. 下拉菜单可选择 admin 或 acl 分组查看对应接口。
3. 通过外部文档链接跳转到项目主页。

提示：实际部署时需替换 your.repo.url 和联系人信息。