Springdoc 常用注解与 Swagger2 对比指南

Springdoc官网：https://springdoc.org/

Swagger2官网：https://swagger.io/

一、Springdoc 常用注解及对应 Swagger2 注解

以下是 Springdoc 的核心注解及其与 Swagger2 的对比，帮助开发者快速迁移和理解差异：

二、详细注解使用示例

1. API 分组与接口描述

// Springdoc
@RestController
@Tag(name = "用户模块", description = "用户注册、登录、查询等操作")
public class UserController {

    @Operation(
        summary = "获取用户信息",
        description = "根据用户ID查询详细信息",
        tags = {"查询类接口"}
    )
    @GetMapping("/users/{id}")
    public User getUser(@Parameter(description = "用户ID", example = "1001") @PathVariable Long id) {
        // ...
    }
}

// Swagger2
@RestController
@Api(tags = "用户模块", description = "用户相关操作")
public class UserController {

    @ApiOperation(value = "获取用户信息", notes = "根据ID查询")
    @GetMapping("/users/{id}")
    public User getUser(@ApiParam("用户ID") @PathVariable Long id) {
        // ...
    }
}

2. 模型字段描述

// Springdoc
public class User {
    @Schema(description = "用户ID", example = "1001", requiredMode = Schema.RequiredMode.REQUIRED)
    private Long id;

    @Schema(description = "用户名", example = "john_doe", maxLength = 20)
    private String username;
}

// Swagger2
public class User {
    @ApiModelProperty(value = "用户ID", example = "1001", required = true)
    private Long id;

    @ApiModelProperty(value = "用户名", example = "john_doe")
    private String username;
}

3. 安全认证配置

// Springdoc
@Configuration
@SecurityScheme(
    name = "BearerAuth",
    type = SecuritySchemeType.HTTP,
    scheme = "bearer",
    bearerFormat = "JWT"
)
public class OpenApiConfig {}

@Operation(summary = "删除用户", security = @SecurityRequirement(name = "BearerAuth"))
@DeleteMapping("/users/{id}")
public void deleteUser(@PathVariable Long id) {
    // ...
}

// Swagger2
@Configuration
public class SwaggerConfig {
    @Bean
    public SecurityConfiguration security() {
        return new SecurityConfiguration(
            "client-id", "client-secret", "realm",
            "app-name", "apiKey", ApiKeyVehicle.HEADER, "Authorization", ","
        );
    }
}

@ApiOperation(value = "删除用户")
@ApiImplicitParams({
    @ApiImplicitParam(name = "Authorization", value = "JWT Token", required = true, dataType = "string", paramType = "header")
})
@DeleteMapping("/users/{id}")
public void deleteUser(@PathVariable Long id) {
    // ...
}

三、Springdoc 与 Swagger2 的核心差异

四、迁移注意事项

1. 依赖替换
   移除 springfox-swagger2 和 springfox-swagger-ui，添加 Springdoc 依赖：

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

2. 注解包替换
   将 io.swagger.annotations 替换为 io.swagger.v3.oas.annotations。

3. 配置调整

   • 文档访问路径：Swagger2 的 swagger-ui.html 变为 Springdoc 的 swagger-ui/index.html。
   • 分组配置：使用 GroupedOpenApi 替代 Docket。

4. 解决常见问题

   • 注解不生效：检查是否使用了正确的包路径。
   • 文档空白：确保未拦截 /v3/api-docs 和 /swagger-ui/** 路径（如 Spring Security 配置）。

五、总结

Springdoc 作为 Swagger2 的现代替代方案，具有以下优势：

• 规范先进：支持 OpenAPI 3.0，覆盖 WebSocket、异步接口等场景。
• 兼容性强：完美适配 Spring Boot 2.6+ 和 3.x。
• 配置简洁：通过注解和配置类即可实现复杂需求（如安全认证、多分组）。

迁移时只需调整依赖、更新注解包路径，并参考上述对比表修改代码，即可快速升级到更健壮的 API 文档方案。