Swagger/OpenAPI 使用规则文档

一、框架概述

1.1 什么是 Swagger/OpenAPI

Swagger 是一个用于设计、构建、文档化和使用 RESTful Web 服务的工具集。它提供了一个交互式的 API 文档界面，允许开发者和用户直接在浏览器中测试 API。

OpenAPI（原 Swagger 规范）是一个用于描述 RESTful API 的规范标准，由 OpenAPI Initiative（OAI）维护。OpenAPI 3.0 是目前最新的版本。

SpringDoc OpenAPI 是 Spring Boot 应用中集成 OpenAPI 3.0 规范的实现，它能够：

  • 自动扫描 Spring MVC 控制器
  • 根据注解生成 API 文档
  • 提供交互式的 Swagger UI 界面
  • 支持在线测试 API 接口

1.2 技术栈

  • SpringDoc OpenAPI: 1.7.0
  • OpenAPI 规范: 3.0
  • Spring Boot: 2.7.18
  • Swagger UI: 集成在 SpringDoc 中（自动提供）

1.3 为什么选择 SpringDoc OpenAPI

  1. 零配置: Spring Boot 自动配置，无需额外配置即可使用
  2. 自动扫描: 自动扫描 Spring MVC 控制器，生成 API 文档
  3. 注解驱动: 使用注解即可描述 API，代码即文档
  4. 交互式界面: 提供 Swagger UI，支持在线测试 API
  5. OpenAPI 3.0: 支持最新的 OpenAPI 3.0 规范
  6. 活跃维护: 社区活跃，更新及时

1.4 Swagger vs OpenAPI

特性 Swagger 2.0 OpenAPI 3.0
规范版本 Swagger 2.0 OpenAPI 3.0
维护组织 SmartBear OpenAPI Initiative
功能 API 文档和测试 API 文档、测试、代码生成
兼容性 较旧 最新标准
本项目使用 ❌ ✅

说明: 本项目使用 OpenAPI 3.0 规范（通过 SpringDoc OpenAPI 实现）。

二、工作原理

2.1 工作流程

┌─────────────────────────────────────────────────────────┐
│  1. 应用启动                                              │
│     SpringDoc 自动扫描 Spring MVC 控制器                  │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────┐
│  2. 解析注解                                              │
│     - @Tag: Controller 分组                              │
│     - @Operation: 接口描述                               │
│     - @Parameter: 参数描述                               │
│     - @RequestBody: 请求体                               │
│     - @ApiResponse: 响应描述                             │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────┐
│  3. 生成 OpenAPI 规范文档                                 │
│     - JSON 格式: /v3/api-docs                            │
│     - YAML 格式: /v3/api-docs.yaml                       │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────┐
│  4. 渲染 Swagger UI                                       │
│     - 访问地址: /swagger-ui/index.html                   │
│     - 交互式界面，支持在线测试                            │
└─────────────────────────────────────────────────────────┘

2.2 核心组件

2.2.1 OpenAPI Bean

SpringDoc 会创建一个 OpenAPI Bean，用于配置 API 文档的基本信息（标题、版本、描述等）。

2.2.2 自动扫描机制

SpringDoc 通过 Spring 的 ApplicationContext 自动扫描：

  • @RestController 注解的类
  • @RequestMapping 注解的方法
  • Spring MVC 的请求映射
2.2.3 注解解析器

SpringDoc 解析以下注解：

  • Controller 级别: @Tag
  • 方法级别: @Operation, @ApiResponse
  • 参数级别: @Parameter, @RequestBody, @PathVariable, @RequestParam
  • 模型级别: @Schema（可选，用于描述数据模型）
2.2.4 Swagger UI 集成

SpringDoc 自动集成 Swagger UI，提供：

  • 可视化的 API 文档界面
  • 在线测试 API 功能
  • 请求/响应示例展示

三、架构设计

3.1 项目中的架构

┌─────────────────────────────────────────────────────────┐
│                   浏览器 (Swagger UI)                     │
│              http://localhost:8080/swagger-ui/index.html │
└────────────────────┬────────────────────────────────────┘
                     │ HTTP 请求
┌────────────────────▼────────────────────────────────────┐
│              Spring Boot 应用                             │
│  ┌──────────────────────────────────────────────────┐   │
│  │  SpringDoc OpenAPI                                │   │
│  │  - 自动扫描 Controller                            │   │
│  │  - 解析注解                                       │   │
│  │  - 生成 OpenAPI 文档                              │   │
│  └──────────────────┬───────────────────────────────┘   │
│                     │                                    │
│  ┌──────────────────▼───────────────────────────────┐   │
│  │  SwaggerConfig                                    │   │
│  │  - 配置 OpenAPI Bean                              │   │
│  │  - 设置 API 基本信息                              │   │
│  └──────────────────┬───────────────────────────────┘   │
│                     │                                    │
│  ┌──────────────────▼───────────────────────────────┐   │
│  │  Controller (SysUserController)                   │   │
│  │  - @Tag: 接口分组                                 │   │
│  │  - @Operation: 接口描述                           │   │
│  │  - @Parameter: 参数描述                           │   │
│  └──────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

3.2 配置层次

1. Maven 依赖 (pom.xml)
   └── springdoc-openapi-ui:1.7.0
   
2. Spring Boot 自动配置
   └── SpringDoc 自动扫描和配置
   
3. 自定义配置 (SwaggerConfig.java)
   └── OpenAPI Bean 配置
   
4. Controller 注解
   └── @Tag, @Operation, @Parameter

3.3 访问端点

端点 说明 示例
/swagger-ui/index.html Swagger UI 界面（推荐） http://localhost:8080/swagger-ui/index.html
/swagger-ui.html Swagger UI 界面（旧版，重定向） http://localhost:8080/swagger-ui.html
/v3/api-docs OpenAPI JSON 文档 http://localhost:8080/v3/api-docs
/v3/api-docs.yaml OpenAPI YAML 文档 http://localhost:8080/v3/api-docs.yaml

四、依赖配置

4.1 Maven 依赖

在 pom.xml 中配置：

<properties>
    <springdoc.version>1.7.0</springdoc.version>
</properties>

<dependencies>
    <!-- SpringDoc OpenAPI (Swagger 3.0) -->
    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-ui</artifactId>
        <version>${springdoc.version}</version>
    </dependency>
</dependencies>

依赖说明:

  • springdoc-openapi-ui: 包含 Swagger UI 和 OpenAPI 3.0 支持
  • 自动包含 springdoc-openapi-webmvc-core（核心功能）
  • 自动包含 swagger-ui（前端界面）

4.2 依赖版本选择

Spring Boot 版本 SpringDoc OpenAPI 版本
2.6.x 1.6.x
2.7.x 1.7.x ✅（本项目）
3.0.x 2.0.x
3.1.x 2.2.x

本项目: Spring Boot 2.7.18 + SpringDoc OpenAPI 1.7.0

五、配置详解

5.1 基础配置（自动配置）

SpringDoc OpenAPI 支持零配置使用，默认配置如下：

  • 扫描路径: 所有 @RestController 注解的类
  • API 文档路径: /v3/api-docs
  • Swagger UI 路径: /swagger-ui/index.html
  • 分组: 默认一个分组（所有接口）

5.2 自定义配置（SwaggerConfig.java）

项目中的配置类：

package pdfc.monitor.config;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/**
 * Swagger/OpenAPI 配置类
 */
@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Monitor API 文档")
                        .version("1.0.0")
                        .description("系统用户管理 API 接口文档")
                        .contact(new Contact()
                                .name("Monitor Team")
                                .email("monitor@example.com"))
                        .license(new License()
                                .name("Apache 2.0")
                                .url("https://www.apache.org/licenses/LICENSE-2.0.html")));
    }
}

配置说明:

  • @Configuration: 标识为配置类
  • @Bean: 创建 OpenAPI Bean
  • Info: API 基本信息（标题、版本、描述、联系方式、许可证）

5.3 高级配置（可选）

5.3.1 配置多个服务器
@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .info(new Info()
                    .title("Monitor API 文档")
                    .version("1.0.0"))
            .servers(Arrays.asList(
                    new Server().url("http://localhost:8080").description("开发环境"),
                    new Server().url("https://api.example.com").description("生产环境")
            ));
}
5.3.2 配置安全认证
@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .info(new Info()
                    .title("Monitor API 文档")
                    .version("1.0.0"))
            .components(new Components()
                    .addSecuritySchemes("bearer-jwt", new SecurityScheme()
                            .type(SecurityScheme.Type.HTTP)
                            .scheme("bearer")
                            .bearerFormat("JWT")));
}
5.3.3 配置分组
@Bean
public GroupedOpenApi publicApi() {
    return GroupedOpenApi.builder()
            .group("public")
            .pathsToMatch("/api/public/**")
            .build();
}

@Bean
public GroupedOpenApi adminApi() {
    return GroupedOpenApi.builder()
            .group("admin")
            .pathsToMatch("/api/admin/**")
            .build();
}
5.3.4 配置文件方式（application.properties）
# SpringDoc OpenAPI 配置
springdoc.api-docs.path=/v3/api-docs
springdoc.swagger-ui.path=/swagger-ui.html
springdoc.swagger-ui.operationsSorter=method
springdoc.swagger-ui.tagsSorter=alpha
springdoc.swagger-ui.tryItOutEnabled=true

六、注解使用

6.1 Controller 级别注解

6.1.1 @Tag

用于对 Controller 进行分组和描述。

使用示例:

@Tag(name = "系统用户管理", description = "系统用户相关的增删改查接口")
@RestController
@RequestMapping("/api/sys/user")
public class SysUserController {
    // ...
}

属性说明:

  • name: 标签名称（必填）
  • description: 标签描述（可选）

6.2 方法级别注解

6.2.1 @Operation

用于描述 API 接口。

使用示例:

@Operation(summary = "新增用户（全字段）", description = "创建新用户，需要提供所有必填字段")
@PostMapping("/add")
public ApiResponse<Integer> add(@RequestBody SysUserVo userVo) {
    // ...
}

属性说明:

  • summary: 接口摘要（简短描述，必填）
  • description: 接口详细描述（可选）
  • tags: 标签（可选，默认使用 Controller 的 @Tag）
  • operationId: 操作 ID（可选，默认使用方法名）

完整示例:

@Operation(
    summary = "分页查询用户",
    description = "分页查询用户列表，支持排序（默认按插入时间倒序）",
    tags = {"系统用户管理"},
    operationId = "getUserPage"
)
@GetMapping("/page")
public ApiResponse<Page<SysUserVo>> getPage(
    @Parameter(description = "页码，从1开始", example = "1") 
    @RequestParam(defaultValue = "1") Integer pageIndex,
    @Parameter(description = "每页数量", example = "10") 
    @RequestParam(defaultValue = "10") Integer pageSize) {
    // ...
}
6.2.2 @ApiResponse

用于描述 API 响应（可选，SpringDoc 会自动推断）。

使用示例:

@Operation(summary = "根据ID查询用户")
@ApiResponses(value = {
    @ApiResponse(responseCode = "200", description = "查询成功"),
    @ApiResponse(responseCode = "404", description = "用户不存在"),
    @ApiResponse(responseCode = "500", description = "服务器错误")
})
@GetMapping("/get/{id}")
public ApiResponse<SysUserVo> getById(@PathVariable Integer id) {
    // ...
}

6.3 参数级别注解

6.3.1 @Parameter

用于描述请求参数（路径参数、查询参数）。

使用示例:

@GetMapping("/get/{id}")
public ApiResponse<SysUserVo> getById(
    @Parameter(description = "用户ID", required = true, example = "1") 
    @PathVariable Integer id) {
    // ...
}

属性说明:

  • description: 参数描述
  • required: 是否必填（默认 false）
  • example: 示例值
  • name: 参数名称（可选，默认使用变量名）

查询参数示例:

@GetMapping("/page")
public ApiResponse<Page<SysUserVo>> getPage(
    @Parameter(description = "页码，从1开始", example = "1") 
    @RequestParam(defaultValue = "1") Integer pageIndex,
    @Parameter(description = "每页数量", example = "10") 
    @RequestParam(defaultValue = "10") Integer pageSize) {
    // ...
}
6.3.2 @RequestBody

用于描述请求体（JSON 格式）。

使用示例:

@PostMapping("/add")
public ApiResponse<Integer> add(
    @RequestBody SysUserVo userVo) {
    // ...
}

说明:

  • SpringDoc 会自动识别 @RequestBody 注解
  • 会自动解析请求体的类型（SysUserVo）
  • 可以在 VO 类上使用 @Schema 注解描述字段（可选）
6.3.3 @Schema（可选）

用于描述数据模型（VO、DTO 等）。

使用示例:

import io.swagger.v3.oas.annotations.media.Schema;

@Schema(description = "系统用户视图对象")
public class SysUserVo {
    
    @Schema(description = "用户ID", example = "1")
    private Integer id;
    
    @Schema(description = "用户姓名", example = "张三", required = true)
    private String name;
    
    @Schema(description = "工作职位", example = "软件工程师")
    private String work;
    
    @Schema(description = "年龄", example = "28", minimum = "1", maximum = "150")
    private Integer age;
    
    // getter/setter...
}

属性说明:

  • description: 字段描述
  • example: 示例值
  • required: 是否必填
  • minimum/maximum: 数值范围
  • pattern: 正则表达式（字符串）

注意: 项目中未使用 @Schema 注解，SpringDoc 会自动推断类型和字段。

七、项目中的使用示例

7.1 Controller 完整示例

package pdfc.monitor.web;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;

@Tag(name = "系统用户管理", description = "系统用户相关的增删改查接口")
@RestController
@RequestMapping("/api/sys/user")
public class SysUserController {

    /**
     * 新增用户（全字段）
     */
    @Operation(summary = "新增用户（全字段）", description = "创建新用户，需要提供所有必填字段")
    @PostMapping("/add")
    public ApiResponse<Integer> add(@RequestBody SysUserVo userVo) {
        // 业务逻辑...
    }

    /**
     * 根据ID查询用户
     */
    @Operation(summary = "根据ID查询用户", description = "根据用户ID查询用户详细信息")
    @GetMapping("/get/{id}")
    public ApiResponse<SysUserVo> getById(
            @Parameter(description = "用户ID", required = true) 
            @PathVariable Integer id) {
        // 业务逻辑...
    }

    /**
     * 分页查询用户
     */
    @Operation(summary = "分页查询用户", description = "分页查询用户列表，支持排序（默认按插入时间倒序）")
    @GetMapping("/page")
    public ApiResponse<Page<SysUserVo>> getPage(
            @Parameter(description = "页码，从1开始", example = "1") 
            @RequestParam(defaultValue = "1") Integer pageIndex,
            @Parameter(description = "每页数量", example = "10") 
            @RequestParam(defaultValue = "10") Integer pageSize) {
        // 业务逻辑...
    }
}

7.2 项目中的接口列表

接口 方法 路径 说明
新增用户（全字段） POST /api/sys/user/add 创建新用户，需要提供所有必填字段
新增用户（选择性字段） POST /api/sys/user/addSelective 创建新用户，只需提供部分字段
根据ID删除用户 DELETE /api/sys/user/delete/{id} 根据用户ID删除指定用户
批量删除用户 DELETE /api/sys/user/deleteBatch 根据用户ID列表批量删除多个用户
更新用户（全字段） PUT /api/sys/user/update 更新用户信息，需要提供所有字段
更新用户（选择性字段） PATCH /api/sys/user/updateSelective 选择性更新用户信息
根据ID查询用户 GET /api/sys/user/get/{id} 根据用户ID查询用户详细信息
批量查询用户 POST /api/sys/user/getBatch 根据多个用户ID批量查询用户信息
分页查询用户 GET /api/sys/user/page 分页查询用户列表，支持排序
查询所有用户 GET /api/sys/user/list 查询所有用户，不分页

八、访问和使用

8.1 访问 Swagger UI

  1. 启动应用:
mvn spring-boot:run
  1. 打开浏览器，访问：
http://localhost:8080/swagger-ui/index.html
  1. 查看 API 文档:
    • 左侧显示所有接口分组（Tags）
    • 点击分组展开，查看该分组下的所有接口
    • 点击接口展开，查看接口详情

8.2 Swagger UI 功能

8.2.1 查看接口信息
  • 接口描述: 显示 @Operation 的 summary 和 description
  • 请求方法: GET、POST、PUT、DELETE 等
  • 请求路径: 完整的 URL 路径
  • 参数说明: 显示所有参数及其描述、类型、是否必填
8.2.2 在线测试 API
  1. 点击 “Try it out” 按钮
  2. 填写参数:
    • 路径参数：直接在路径中填写
    • 查询参数：在 Parameters 区域填写
    • 请求体：在 Request body 区域填写 JSON
  3. 点击 “Execute” 按钮
  4. 查看响应:
    • 响应状态码
    • 响应头
    • 响应体（JSON 格式）
8.2.3 查看请求/响应示例
  • 请求示例: 显示请求的 JSON 格式
  • 响应示例: 显示响应的 JSON 格式（根据返回类型自动生成）

8.3 访问 OpenAPI JSON 文档

访问以下地址获取 OpenAPI 规范文档（JSON 格式）：

http://localhost:8080/v3/api-docs

用途:

  • 导入到 Postman、Insomnia 等 API 测试工具
  • 使用代码生成工具生成客户端 SDK
  • 集成到其他 API 文档工具

8.4 访问 OpenAPI YAML 文档

访问以下地址获取 OpenAPI 规范文档（YAML 格式）：

http://localhost:8080/v3/api-docs.yaml

九、最佳实践

9.1 注解使用规范

9.1.1 Controller 级别
// ✅ 正确：使用 @Tag 描述 Controller
@Tag(name = "系统用户管理", description = "系统用户相关的增删改查接口")
@RestController
@RequestMapping("/api/sys/user")
public class SysUserController {
    // ...
}

// ❌ 错误：缺少 @Tag，接口会显示在 "default" 分组中
@RestController
@RequestMapping("/api/sys/user")
public class SysUserController {
    // ...
}
9.1.2 方法级别
// ✅ 正确：使用 @Operation 描述接口
@Operation(summary = "新增用户", description = "创建新用户，需要提供所有必填字段")
@PostMapping("/add")
public ApiResponse<Integer> add(@RequestBody SysUserVo userVo) {
    // ...
}

// ❌ 错误：缺少 @Operation，接口描述不清晰
@PostMapping("/add")
public ApiResponse<Integer> add(@RequestBody SysUserVo userVo) {
    // ...
}
9.1.3 参数级别
// ✅ 正确：使用 @Parameter 描述参数
@GetMapping("/get/{id}")
public ApiResponse<SysUserVo> getById(
    @Parameter(description = "用户ID", required = true, example = "1") 
    @PathVariable Integer id) {
    // ...
}

// ❌ 错误：缺少 @Parameter，参数说明不清晰
@GetMapping("/get/{id}")
public ApiResponse<SysUserVo> getById(@PathVariable Integer id) {
    // ...
}

9.2 接口描述规范

9.2.1 Summary（摘要）
  • 要求: 简短、清晰，一句话概括接口功能
  • 格式: 动词 + 名词，如 “新增用户”、“查询用户列表”
  • 长度: 建议不超过 20 个字符
// ✅ 正确
@Operation(summary = "新增用户")

// ❌ 错误：太长
@Operation(summary = "这是一个用于新增用户的接口，需要提供用户的所有必填字段")
9.2.2 Description（描述）
  • 要求: 详细说明接口功能、使用场景、注意事项
  • 格式: 可以多行，使用中文描述
  • 内容: 包括参数说明、返回值说明、异常情况
// ✅ 正确
@Operation(
    summary = "分页查询用户",
    description = "分页查询用户列表，支持排序（默认按插入时间倒序）。" +
                  "页码从1开始，每页数量建议不超过100。"
)

9.3 参数描述规范

9.3.1 必填参数
// ✅ 正确：明确标识必填参数
@Parameter(description = "用户ID", required = true)
@PathVariable Integer id
9.3.2 可选参数
// ✅ 正确：提供默认值和示例
@Parameter(description = "页码，从1开始", example = "1")
@RequestParam(defaultValue = "1") Integer pageIndex
9.3.3 请求体
// ✅ 正确：请求体类型清晰
@PostMapping("/add")
public ApiResponse<Integer> add(@RequestBody SysUserVo userVo) {
    // ...
}

9.4 响应描述规范

9.4.1 统一响应格式

项目中使用 ApiResponse<T> 作为统一响应格式：

public class ApiResponse<T> {
    private Integer code;      // 状态码
    private String message;    // 消息
    private T data;           // 数据
}
9.4.2 响应示例

在 Swagger UI 中，响应示例会自动根据返回类型生成。如果需要自定义，可以使用 @ApiResponse 注解：

@Operation(summary = "根据ID查询用户")
@ApiResponses(value = {
    @ApiResponse(responseCode = "200", description = "查询成功"),
    @ApiResponse(responseCode = "404", description = "用户不存在"),
    @ApiResponse(responseCode = "500", description = "服务器错误")
})
@GetMapping("/get/{id}")
public ApiResponse<SysUserVo> getById(@PathVariable Integer id) {
    // ...
}

十、常见问题

10.1 Swagger UI 无法访问

问题：访问 /swagger-ui/index.html 返回 404

可能原因:

  1. 依赖未正确添加
  2. Spring Boot 版本不兼容
  3. 路径配置错误

解决方法:

  1. 检查 pom.xml 中是否添加了 springdoc-openapi-ui 依赖
  2. 检查 Spring Boot 版本是否与 SpringDoc 版本兼容
  3. 尝试访问 /swagger-ui.html（旧版路径）

10.2 接口未显示在 Swagger UI 中

问题：Controller 中的接口没有出现在 Swagger UI 中

可能原因:

  1. Controller 未使用 @RestController 注解
  2. 方法未使用 @RequestMapping 系列注解
  3. 路径被排除（如果配置了路径过滤）

解决方法:

  1. 确保 Controller 使用 @RestController 注解
  2. 确保方法使用 @GetMapping、@PostMapping 等注解
  3. 检查是否有路径过滤配置

10.3 接口描述不完整

问题：接口在 Swagger UI 中显示为默认描述

解决方法:

  1. 添加 @Operation 注解描述接口
  2. 添加 @Parameter 注解描述参数
  3. 添加 @Tag 注解对 Controller 进行分组

10.4 请求体类型无法识别

问题：Swagger UI 中请求体显示为 “object” 而不是具体的类型

解决方法:

  1. 确保请求体类型（VO/DTO）是公共类
  2. 确保类有 getter/setter 方法（或使用 Lombok @Data）
  3. 可选：使用 @Schema 注解描述字段

10.5 复杂类型显示不正确

问题：泛型类型（如 List<T>、Page<T>）显示不正确

说明:

  • SpringDoc 会自动处理常见的泛型类型
  • 对于自定义泛型类型，可能需要额外配置

解决方法:

  1. 使用 @Schema 注解明确指定类型
  2. 或者使用 @ApiResponse 注解描述响应类型

十一、高级功能

11.1 多环境配置

11.1.1 开发环境
# application-dev.properties
springdoc.swagger-ui.enabled=true
springdoc.api-docs.enabled=true
11.1.2 生产环境
# application-prod.properties
springdoc.swagger-ui.enabled=false
springdoc.api-docs.enabled=false

11.2 自定义 Swagger UI 配置

# application.properties
# Swagger UI 配置
springdoc.swagger-ui.path=/swagger-ui.html
springdoc.swagger-ui.operationsSorter=method
springdoc.swagger-ui.tagsSorter=alpha
springdoc.swagger-ui.tryItOutEnabled=true
springdoc.swagger-ui.filter=true
springdoc.swagger-ui.displayRequestDuration=true

11.3 接口分组

@Bean
public GroupedOpenApi publicApi() {
    return GroupedOpenApi.builder()
            .group("public")
            .pathsToMatch("/api/public/**")
            .build();
}

@Bean
public GroupedOpenApi adminApi() {
    return GroupedOpenApi.builder()
            .group("admin")
            .pathsToMatch("/api/admin/**")
            .build();
}

11.4 安全认证配置

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .info(new Info()
                    .title("Monitor API 文档")
                    .version("1.0.0"))
            .components(new Components()
                    .addSecuritySchemes("bearer-jwt", new SecurityScheme()
                            .type(SecurityScheme.Type.HTTP)
                            .scheme("bearer")
                            .bearerFormat("JWT")))
            .addSecurityItem(new SecurityRequirement().addList("bearer-jwt"));
}

十二、总结

12.1 核心要点

  1. 依赖配置: 添加 springdoc-openapi-ui 依赖
  2. 自动配置: SpringDoc 自动扫描和配置，无需额外配置
  3. 自定义配置: 通过 SwaggerConfig 配置 API 基本信息
  4. 注解使用: 使用 @Tag、@Operation、@Parameter 描述 API
  5. 访问地址: /swagger-ui/index.html 查看 Swagger UI

12.2 项目配置总结

✅ 已完成的配置:

  • ✅ 依赖已添加（springdoc-openapi-ui:1.7.0）
  • ✅ 配置类已创建（SwaggerConfig.java）
  • ✅ Controller 已添加注解（@Tag、@Operation、@Parameter）
  • ✅ Swagger UI 可正常访问
  • ✅ API 文档完整显示

12.3 使用建议

  1. 开发阶段: 使用 Swagger UI 进行接口测试和调试
  2. 文档维护: 及时更新接口描述和参数说明
  3. 团队协作: 通过 Swagger UI 分享 API 文档给前端和其他团队
  4. 生产环境: 建议关闭 Swagger UI（通过配置禁用）

文档版本: 1.0
最后更新: 2025-11-13
维护者: 项目团队

# java # 开发语言
Logo
快递鸟一站式物流API解决方案

电商企业物流数字化转型必备！快递鸟 API 接口，72 小时快速完成物流系统集成。全流程实战1V1指导，营造开放的API技术生态圈。

更多推荐

如何用Saleor打造AI驱动的电商平台：10个关键应用场景解析

Saleor是一个高性能、可组合的无头电商API平台，它通过灵活的架构设计为电商业务提供强大支持。在AI技术快速发展的今天，Saleor的模块化设计使其能够无缝集成各类人工智能功能，为电商企业带来智能化升级。本文将详细介绍Saleor平台中机器学习和AI技术的10个关键应用场景，帮助你快速理解如何利用这一开源工具构建智能电商系统。## 1. 智能产品搜索优化Saleor内置了强大的产品搜索

avatar 快递鸟社区

Pie库测试驱动开发：如何为切片操作编写高质量的单元测试

Pie库是一个专注于类型安全和性能的Go语言切片与映射操作工具库。本文将详细介绍如何通过测试驱动开发（TDD）为Pie库的切片操作编写高质量单元测试，帮助开发者确保代码可靠性并提升开发效率。## 为什么选择测试驱动开发？测试驱动开发（TDD）是一种先编写测试用例再实现功能的开发方法。对于Pie库这类工具库而言，TDD带来三大核心价值：- **类型安全保障**：通过测试验证切片操作的类型约

avatar 快递鸟社区

AutoLoadCache高并发场景实战：电商系统缓存优化案例分享

AutoLoadCache是基于AOP+Annotation等技术实现的高效缓存管理解决方案，通过缓存与业务逻辑解耦，结合异步刷新及"拿来主义机制"，为电商等高并发场景提供稳定可靠的缓存优化能力。在秒杀、大促等流量峰值场景下，合理使用AutoLoadCache可显著降低数据库压力，提升系统响应速度。## 电商系统面临的缓存挑战 🔥在电商平台中，商品详情、库存数量、用户购物车等高频访问数据

avatar 快递鸟社区