SpringBoot3整合OpenAPI3(Swagger3)完整指南

以下是 Spring Boot 3 集成 OpenAPI 3（Swagger 3） 的完整指南，结合最新实践和官方规范整理，涵盖基础配置、注解使用、安全认证及生产环境优化。

一、环境准备与依赖配置

1. 版本兼容性

• Spring Boot 3.x：必须使用 springdoc-openapi-starter-webmvc-ui（基于 OpenAPI 3.0 规范）
• Spring Boot 2.x：需用 springdoc-openapi-ui（本指南以 Spring Boot 3 为例）

2. 添加依赖

<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.3.0</version> <!-- Spring Boot 3.x 推荐 -->
</dependency>

⚠️ 注意：

• 仅需此依赖，添加其他 Swagger 依赖可能导致冲突（如 NoSuchMethodError）
• 生产环境需关闭 Swagger（通过 Profile 控制）

二、基础配置与启动

1. 零配置快速启动

• 添加依赖后直接启动应用
• 访问路径：
  • Swagger UI 界面：http://localhost:8080/swagger-ui/index.html
  • OpenAPI JSON 描述：http://localhost:8080/v3/api-docs

2. 自定义全局信息（可选）

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;@Configuration
public class OpenApiConfig {@Beanpublic OpenAPI customOpenAPI() {return new OpenAPI().info(new Info().title("电商平台 API"