最推荐方式是使用springdoc-openapi-starter-webmvc-ui，它开箱即用、原生支持Jakarta EE 9+和Spring 6，无需兼容补丁；引入starter后访问/swagger-ui.html和/v3/api-docs即可获得自动扫描生成的交互式文档。

Spring Boot 3.x 集成 OpenAPI 3.0 最推荐的方式是使用 springdoc-openapi-starter-webmvc-ui，它开箱即用、原生支持 Jakarta EE 9+ 和 Spring 6，无需修改路径匹配策略或打兼容补丁。

基础依赖引入

在 pom.xml 中添加：

• spring-boot-starter-web（必须）
• springdoc-openapi-starter-webmvc-ui（推荐最新稳定版，如 2.6.0 或 2.5.0）

注意：不要混用旧版 springfox-swagger2 或 springdoc-openapi-ui 单独包，starter 已内置 swagger-ui、core 和 annotations，避免版本冲突。

启动即用，无需额外配置

引入 starter 后直接启动应用，访问以下地址即可看到交互式文档：

Alibabacloud Sdk Client Initialization For Java

在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。

下载

• Swagger UI 页面：http://localhost:8080/swagger-ui.html
• OpenAPI JSON 文档：http://localhost:8080/v3/api-docs

它会自动扫描所有 @RestController 类、@RequestMapping 系列注解、方法参数、返回值类型及 JSR-303 校验注解（如 @NotBlank、@Min），生成结构化描述。

自定义文档元信息

通过 @Configuration 类返回 OpenAPI Bean，设置标题、版本、联系人等：

• 使用 io.swagger.v3.oas.models.OpenAPI
• 调用 .info(new Info().title("...").version("v1.0.0").contact(...))
• 可选添加全局请求头、默认响应码、服务器地址等

生产环境安全关闭

避免文档暴露在生产环境，建议在 application-prod.yml 中禁用：

• springdoc.api-docs.enabled=false
• springdoc.swagger-ui.enabled=false
• 或通过 profile 控制，仅在 dev 或 test 激活

这样既保留开发调试能力，又满足安全合规要求。