spring boot 集成 swagger 自动生成接口文档的核心是自动扫描 controller 提取接口信息，生成 openapi 规范 json 并提供交互式 ui；spring boot 2.x 用 springfox-swagger2，3.x 必须用 springdoc-openapi-starter-webmvc-ui，访问地址分别为 /swagger-ui.html 和 /swagger-ui/index.html（knife4j 为 /doc.html）。
Spring Boot 集成 Swagger 自动生成接口文档，核心是让框架自动扫描 Controller 层代码，提取路径、参数、返回值等信息，生成符合 OpenAPI 规范的 JSON 描述，并提供可交互的 Web 界面。关键不在于“写文档”，而在于“用代码描述接口”，文档随代码实时更新。
选对版本：Spring Boot 2.x vs 3.x 的技术栈差异
Spring Boot 版本决定你该用哪套工具链：
-
Spring Boot 2.x（如 2.7.x）：推荐使用
springfox-swagger2+springfox-swagger-ui（例如 2.9.2 或 3.0.0），配合@EnableSwagger2注解启用；访问地址为/swagger-ui.html。 -
Spring Boot 3.x（含 Jakarta EE 9+）：
springfox已不兼容，必须切换到springdoc-openapi生态，引入springdoc-openapi-starter-webmvc-ui；默认访问地址是/swagger-ui.html或/swagger-ui/index.html（取决于版本），Knife4j 增强版则用/doc.html。 - 旧项目若混用
springfox和springdoc，会出现 Bean 冲突或 UI 加载失败，务必清理干净再重配。
基础配置：三步完成最小可用集成
以 Spring Boot 3.x + springdoc 为例（最主流且官方推荐的组合）：
Alibabacloud Sdk Client Initialization For Java
下载
在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。
-
加依赖：在
pom.xml中引入
-
零配置启动：无需 Java 配置类，依赖引入后直接启动应用，访问
http://localhost:8080/swagger-ui.html即可见文档界面（前提是 Controller 有标准 Spring MVC 注解，如@GetMapping）。 -
控制开关：可在
application.yml中关闭生产环境暴露
api-docs:
enabled: false
swagger-ui:
enabled: false
增强可读性：用注解补充接口语义
默认扫描能识别路径和 HTTP 方法，但参数含义、示例值、错误码等需手动标注。推荐使用 @Operation、@Parameter、@Schema（springdoc）或 @Api、@ApiOperation（springfox）：
- 在 Controller 类上加
@Tag(name = "用户管理", description = "登录、注册等操作")分组归类 - 在方法上加
@Operation(summary = "用户登录", description = "根据手机号和密码获取 token") - 对请求体对象字段加
@Schema(description = "手机号，11位数字", example = "13800138000") - 查询参数用
@Parameter(description = "页码，从1开始") @RequestParam Integer page
安全与部署注意事项
Swagger 页面本质是开发调试工具，上线时需防范风险：
-
路径放行：若项目用了 Spring Security，需在配置中放行 swagger 相关路径，例如：
/v3/api-docs/**、/swagger-ui/**、/doc.html（Knife4j） -
环境隔离：通过
@Profile("dev")注解配置类，或用springdoc.api-docs.enabled=${SWAGGER_ENABLED:true}控制是否加载 -
避免敏感信息泄露：不要在
@Schema的example中填写真实密码、密钥；禁用springdoc.show-actuator防止暴露健康端点细节
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
