Spring Boot 集成 Swagger3 的本质是通过代码即文档方式自动生成 OpenAPI 3.0 描述并提供 Swagger UI 交互界面；需根据 Spring Boot 版本选择对应依赖，推荐 Spring Boot 3.x 使用 springdoc-openapi-starter-webmvc-ui，三步启用且支持注解补全语义与生产环境安全控制。
Spring Boot 集成 Swagger3 的本质，是用 代码即文档 的方式，让接口定义自动产出 OpenAPI 3.0 格式的描述，并通过 Swagger UI 提供可视化、可调试的交互界面。关键不在于写文档，而在于写好 Controller 和 DTO，并用标准注解补充语义。
看准 Spring Boot 版本，选对依赖
版本决定技术栈，不能错配：
- Spring Boot 2.x（如 2.7.x）：可用
springfox-boot-starter（3.0.0），但已停止维护，不建议新项目使用； - Spring Boot 3.x（含 Jakarta EE 9+）：必须用 springdoc-openapi，springfox 完全不兼容；
- 推荐 starter：
springdoc-openapi-starter-webmvc-ui（最新稳定版如 2.5.0），开箱即用，无需额外配置类。
三步快速启用，零配置起步
以 Spring Boot 3.x 为例：
Alibabacloud Sdk Client Initialization For Java
下载
在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。
- 加依赖：在
pom.xml中引入 starter； - 写接口：Controller 使用
@GetMapping、@PostMapping等标准注解，DTO 字段用@Schema描述； - 启动访问：
http://localhost:8080/swagger-ui.html或/swagger-ui/index.html即可见交互式文档。
用注解补全语义，让文档真正可用
基础扫描只能识别路径和方法，参数含义、示例、错误码等需手动标注：
-
@Operation(summary = "用户登录", description = "返回 JWT token")—— 描述接口用途； -
@Parameter(name = "username", description = "用户名，长度3-20", required = true)—— 注明参数细节； -
@Schema(description = "手机号，11位数字", example = "13812345678", minLength = 11, maxLength = 11)—— 补充字段说明与样例； - 全局信息（如标题、版本）可在
application.yml中统一配置：
api-docs:
path: /v3/api-docs
swagger-ui:
path: /swagger-ui.html
default-flat-spec: true
info:
title: 用户中心 API
version: 1.0.0
description: 提供用户注册、登录、信息管理等功能
生产环境安全控制
文档只应在开发/测试环境暴露：
- 在
application-prod.yml中关闭：
api-docs:
enabled: false
swagger-ui:
enabled: false
- 也可通过 Profile 控制，如启动时加
--spring.profiles.active=prod； - 若需更细粒度权限（如仅允许内网或登录后访问），可结合 Spring Security 配置路径拦截。
