Java整合Swagger环境搭建教程

本文详细介绍了在Java（尤其是Spring Boot）项目中快速集成Swagger3（即SpringDoc OpenAPI）的完整实践指南：从引入轻量、现代化的springdoc-openapi-starter-webmvc-ui依赖开始，到通过简洁的YAML配置精准控制扫描包、API文档路径与UI访问地址，再到利用@Tag、@Operation、@Hidden等注解实现接口分组、描述与可见性管理，最后强调零配置启动优势及常见注意事项（如Security放行规则）。整个过程无需手动编写配置类或启用旧版注解，开箱即用，让API文档自动生成、实时可视化与在线调试真正变得简单高效。

在Java项目中集成Swagger，主要是为了让API接口自动生成文档并提供在线调试界面。核心是引入Swagger依赖、配置扫描路径和启用相关功能，Spring Boot项目通常用Swagger3（即SpringDoc OpenAPI），它不再依赖Swagger2的注解体系，也无需单独启动Swagger UI服务。

添加Maven依赖

使用SpringDoc OpenAPI替代旧版Swagger2，推荐最新稳定版。在pom.xml中加入：

• springdoc-openapi-starter-webmvc-ui：整合OpenAPI规范 + WebMvc + 自带UI

示例依赖（以Spring Boot 3.x为例）：

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>2.3.0</version>
</dependency>

若用Spring Boot 2.x，可选springdoc-openapi-webmvc-core + springdoc-openapi-ui组合，版本注意匹配。

基础配置（application.yml）

默认情况下，SpringDoc已自动配置好基础功能。如需自定义，可在application.yml中设置：

• server.servlet.context-path：若项目有上下文路径，Swagger UI地址会自动适配
• springdoc.api-docs.path：修改OpenAPI JSON路径，如/v3/api-docs
• springdoc.swagger-ui.path：修改UI访问路径，如/swagger-ui.html
• springdoc.packages-to-scan：指定要扫描的Controller包（不填则全扫，建议明确指定）

常见配置示例：

springdoc:
  packages-to-scan: com.example.demo.controller
  api-docs:
    path: /api-docs
  swagger-ui:
    path: /swagger-ui
    doc-expansion: none

控制接口可见性与分组

多个模块或环境可能需要区分API展示范围：

• 用@Tag标注Controller，归类接口
• 用@Operation描述单个接口功能
• 通过@Hidden隐藏不需要暴露的接口
• 多分组场景下，定义多个GroupedOpenApi Bean，按路径或包隔离

例如定义“用户组”和“订单组”，只需创建两个GroupedOpenApi bean，分别设置pathsToMatch或packagesToScan即可。

验证与访问

启动项目后，直接访问：

• Swagger UI页面：http://localhost:8080/swagger-ui（路径按配置为准）
• OpenAPI JSON文档：http://localhost:8080/api-docs

确保Controller类上有@RestController或@Controller，方法有明确的HTTP映射（如@GetMapping），且未被@Hidden标记，接口就会自动出现在UI中。

基本上就这些。不需要额外写配置类，也不用@EnableSwagger2注解——SpringDoc是零配置启动，重点在于依赖对、包扫描准、路径没被拦截（比如Spring Security需放行/swagger-ui/**和/v3/api-docs/**）。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Java整合Swagger环境搭建教程》文章吧，也可关注golang学习网公众号了解相关技术文章。