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 {

    @Bean
    public 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-docs
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-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