当前位置：首页 > news >正文

spring boot 3集成swagger

news 来源：原创 2025/7/2 9:18:53

Spring Boot 3 集成 Swagger 的过程与之前版本相比有一些变化，主要是因为 `springfox` 库已经停止更新，并且不再支持新的 Spring Boot 版本。因此，对于 Spring Boot 3 来说，推荐使用 `springdoc-openapi` 作为集成 Swagger 的解决方案，它完全支持 OpenAPI 3 规范并且兼容最新的 Spring Boot 和 Java 版本。

以下是集成步骤的概述：

### 1. 添加 Maven 依赖

首先，在你的 `pom.xml` 文件中添加 `springdoc-openapi-starter-webmvc-ui` 依赖：

```xml
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.1.0</version> 
</dependency>
```

确保你也有 `spring-boot-starter-web` 依赖，因为它是必要的：

```xml
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
```

### 2. 编写配置类（可选）

对于基本的设置，通常不需要额外的配置类。如果你需要自定义一些行为，比如分组、安全配置等，你可以创建一个配置类来定制 `springdoc-openapi` 的行为。

例如，你可以这样配置 API 文档的基本信息：

```java
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {

@Bean
public GroupedOpenApi publicApi() {
return GroupedOpenApi.builder()
.group("springshop-public")
.pathsToMatch("/public/**")
.build();
}
}
```

### 3. 使用 Swagger 注解

在你的控制器中使用 Swagger 提供的注解来描述 API。例如：

```java
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api")
@Tag(name = "示例 API", description = "示例 API 描述")
public class ExampleController {

@Operation(summary = "获取信息", description = "这是一个获取信息的例子")
@GetMapping("/info")
public String getInfo(@Parameter(description = "用户ID") String userId) {
return "User ID is: " + userId;
}
}
```

### 4. 访问 Swagger UI

完成上述配置后，启动应用程序并访问 `http://localhost:8080/swagger-ui.html` 或者 `http://localhost:8080/swagger-ui/index.html` 即可查看和测试你的 API 文档。

请注意，具体的路径可能会根据 springdoc-openapi 的版本有所不同，如果遇到问题，请查阅官方文档或项目 GitHub 页面上的说明。此外，为了安全考虑，在生产环境中应该关闭 Swagger UI 的访问，可以通过配置文件来实现：

```properties
springdoc.api-docs.enabled=false
springdoc.swagger-ui.enabled=false
```

以上是集成 Swagger 到 Spring Boot 3 的基本步骤。如果有更复杂的需求，如安全性配置、多分组等，可以进一步参考 `springdoc-openapi` 的官方文档进行深入配置。

相关文章：