Java Spring Boot项目中集成Swagger完整步骤

在Spring Boot项目中集成Swagger可以方便地生成API文档，支持在线测试接口。以下是详细的集成步骤：

---

​1. 添加依赖​

在pom.xml中添加Swagger的依赖（以Springfox为例，这是最常用的Swagger实现）：

<!-- Springfox Swagger2 -->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>3.0.0</version> <!-- 注意版本兼容性 -->
</dependency><!-- Springfox Swagger UI（提供可视化界面） -->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>3.0.0</version>
</dependency>

​注意​：

• 如果使用Spring Boot 3.x，Springfox可能不完全兼容（因为Springfox已停止维护）。推荐改用 ​SpringDoc OpenAPI​（见下文替代方案）。
• Springfox 3.0.0需要Java 8+，且与Spring Boot 2.x兼容性较好。

2. 配置Swagger​

创建一个配置类（如SwaggerConfig.java），启用Swagger并配置基本信息：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;@Configuration
public class SwaggerConfig {@Beanpublic Docket api() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()// 指定扫描的包路径（替换为你的Controller包路径）.apis(RequestHandlerSelectors.basePackage("com.example.controller"))// 指定路径匹配规则（这里匹配所有路径）.paths(PathSelectors.any()).build();}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("Spring Boot API文档").description("RESTful API接口文档").version("1.0").build();}
}

3. 访问Swagger UI​

启动Spring Boot应用后，访问以下URL查看Swagger界面：

• ​Swagger UI: http://localhost:8080/swagger-ui.html
• ​API JSON文档: http://localhost:8080/v2/api-docs

---

​4. 替代方案：SpringDoc OpenAPI（推荐用于Spring Boot 3.x）​​

如果使用Spring Boot 3.x，建议改用 ​SpringDoc OpenAPI​（支持OpenAPI 3.0标准），步骤如下：

​1. 添加依赖

<!-- SpringDoc OpenAPI UI -->
<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.1.0</version> <!-- 检查最新版本 -->
</dependency>

2. 访问界面​

• ​Swagger UI: http://localhost:8080/swagger-ui/index.html
• ​OpenAPI JSON: http://localhost:8080/v3/api-docs

​3. 自定义配置（可选）​​

通过application.yml或application.properties配置：

springdoc:api-docs:path: /v3/api-docsswagger-ui:path: /swagger-ui.htmltags-sorter: alphaoperations-sorter: alpha

5. 常见问题​

1. ​404错误​：

   • 检查依赖版本是否与Spring Boot版本兼容。
   • 确保Controller类有@RestController或@Controller注解，且方法有@RequestMapping或其衍生注解（如@GetMapping）。

2. ​Spring Boot 3.x兼容性​：

   • Springfox已不再维护，强烈建议使用SpringDoc OpenAPI。

3. ​分组API​：

   • 可以通过多个Docket Bean实现API分组（Springfox）或使用SpringDoc的GroupedOpenApi。

6. 示例项目结构

src/main/java
└── com.example├── controller│   └── UserController.java  # 示例Controller└── config└── SwaggerConfig.java   # Swagger配置类

通过以上步骤，你可以快速在Spring Boot中集成Swagger，生成清晰的API文档并支持在线测试。如果需要更高级的功能（如OAuth2安全集成、自定义UI等），可以参考Springfox官方文档或SpringDoc官方文档。

Swagger常见访问地址

Swagger本地常见访问地址主要取决于Swagger版本和是否集成增强UI​（如Knife4j），具体如下：

​1. Swagger 2.x（旧版，如Springfox）​​

• ​默认路径​：
  http://localhost:8080/swagger-ui.html
  • 若项目有上下文路径​（如/api），则需追加路径：
    http://localhost:8080/api/swagger-ui.html

​2. Swagger 3.x（新版，如SpringDoc OpenAPI）​​

• ​默认路径​：
  http://localhost:8080/swagger-ui/index.html
  • 若集成Knife4j增强UI，则路径为：
    http://localhost:8080/doc.html