首页 › Spring Boot › API 文档 › Springdoc OpenAPI 3

Spring Boot 3.x 不推荐使用已停更的 SpringFox，应使用 springdoc-openapi 生成 OpenAPI 3 规范文档。

集成

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

添加依赖后无需额外配置，启动应用即可访问：

• OpenAPI 规范：http://localhost:8080/v3/api-docs
• Swagger UI：http://localhost:8080/swagger-ui/index.html

定制文档信息

通过 @Bean 配置 API 基本信息：

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("用户管理系统 API")
                        .version("1.0.0")
                        .description("用户 CRUD 与权限管理接口"))
                .addSecurityItem(new SecurityRequirement().addList("bearerAuth"))
                .components(new Components()
                        .addSecuritySchemes("bearerAuth",
                                new SecurityScheme()
                                        .type(SecurityScheme.Type.HTTP)
                                        .scheme("bearer")
                                        .bearerFormat("JWT")));
    }
}

在 Controller 中添加描述

springdoc-openapi 自动扫描 @RestController 上的注解并生成文档。也可以通过 @Operation 和 @Schema 提供更详细的描述：

@RestController
@RequestMapping("/api/users")
public class UserController {

    @Operation(summary = "获取用户列表", description = "分页查询用户，默认每页 20 条")
    @GetMapping
    public Result<List<User>> list(
            @Parameter(description = "页码，从 0 开始")
            @RequestParam(defaultValue = "0") int page,
            @Parameter(description = "每页条数")
            @RequestParam(defaultValue = "20") int size) {
        return Result.success(userService.findAll(page, size));
    }

    @Operation(summary = "创建用户")
    @PostMapping
    public Result<User> create(@Valid @RequestBody UserCreateRequest request) {
        return Result.success(userService.create(request));
    }
}

@Schema(description = "创建用户请求")
public class UserCreateRequest {

    @Schema(description = "用户名", example = "张三")
    @NotBlank
    private String username;

    @Schema(description = "年龄", example = "25")
    @Min(0)
    private Integer age;
}

分组（多版本 API）

可以通过 GroupedOpenApi 将文档分组：

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

@Bean
public GroupedOpenApi adminApi() {
    return GroupedOpenApi.builder()
            .group("admin")
            .pathsToMatch("/admin/**")
            .build();
}

访问 /swagger-ui/index.html 时顶部可选择分组。

生产环境关闭

在生产环境中关闭文档端点：

springdoc:
  api-docs:
    enabled: false
  swagger-ui:
    enabled: false

或通过 Profile 控制：仅 dev 环境开启。

生产意识：生产关闭 API 文档端点只是第一道防线。即使端点关闭，/v3/api-docs 对应的 Bean 仍在上下文中，可能通过其他路径泄露信息。更安全的做法是按 Profile 条件注册配置类——将 OpenApiConfig 加上 @Profile("dev")，生产环境连 Bean 都不会创建。

小结

• springdoc-openapi 是 Boot 3 时代推荐的 OpenAPI 工具，SpringFox 已停更。
• 添加依赖即可自动生成 OpenAPI 规范，Swagger UI 开箱可用。
• @Operation / @Schema / @Parameter 丰富文档细节。
• GroupedOpenApi 支持多版本/多分组文档。
• 易错：springdoc-openapi 的 groupId 从 org.springdoc 改为 org.springdoc（注意是 springdoc 而非 swagger 包）。版本与 Spring Boot 3.x 对齐，引入前可查官方发布说明确认兼容性。
• 思考任务：为已有 API 添加 @Operation 描述，启动后访问 /swagger-ui/index.html 验证文档展示是否符合预期。

上一节：Spring 测试基础

下一节：数据访问

贡献者: 布欧-Lewyon