JDK17/SpringBoot3升级：SpringFox转SpringDoc时@Authorization转换困境

直接替换@ApiOperation #

把原代码里的@ApiOperation替换为SpringDoc的@Operation（包路径：io.swagger.v3.oas.annotations.Operation），value属性可以直接沿用。

替换@Authorization与@AuthorizationScope #

SpringDoc没有直接对应这两个注解的API，需要通过全局安全方案配置+接口级安全关联来实现相同效果：

1. 全局定义OAuth2安全方案 #

新建配置类，定义名为internalOAuth的OAuth2安全方案，同时声明所需的作用域及描述：

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.security.OAuthFlow;
import io.swagger.v3.oas.models.security.OAuthFlows;
import io.swagger.v3.oas.models.security.Scopes;
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .components(new io.swagger.v3.oas.models.Components()
                        .addSecuritySchemes("internalOAuth", new SecurityScheme()
                                .type(SecurityScheme.Type.OAUTH2)
                                .flows(new OAuthFlows()
                                        // 根据你的实际OAuth2类型选择，这里用授权码模式举例
                                        .authorizationCode(new OAuthFlow()
                                                .scopes(new Scopes()
                                                        .addString("some_scope_xxx", "Xxxxxx")
                                                        .addString("com.example.class", "Xxxxxx"))
                                                // 补充你的授权服务器地址（必填）
                                                .authorizationUrl("https://your-auth-server/authorize")
                                                .tokenUrl("https://your-auth-server/token")))));
    }
}

2. 接口方法上关联安全方案与作用域 #

在@Operation的security属性中指定要使用的安全方案名称，并明确所需的作用域：

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class YourController {
    @Operation(
            value = "Do XYZ",
            security = {
                    @SecurityRequirement(
                            name = "internalOAuth",
                            scopes = {"some_scope_xxx", "com.example.class"}
                    )
            }
    )
    @GetMapping("/xyz")
    public String doXyz() {
        return "operation result";
    }
}

可选：用@SecurityScope细化作用域描述 #

如果需要在接口上单独定义作用域描述（而非全局统一），可以配合@SecurityScopes和@SecurityScope使用：

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.security.SecurityScopes;
import io.swagger.v3.oas.annotations.security.SecurityScope;

// ...
    @Operation(
            value = "Do XYZ",
            security = {
                    @SecurityRequirement(name = "internalOAuth")
            }
    )
    @SecurityScopes({
            @SecurityScope(name = "some_scope_xxx", description = "Xxxxxx"),
            @SecurityScope(name = "com.example.class", description = "Xxxxxx")
    })
// ...

注意事项 #

• 全局配置的安全方案名称internalOAuth必须和接口@SecurityRequirement的name完全一致
• 作用域描述既可以在全局配置中定义，也可以在接口注解中补充，接口级的描述会覆盖全局
• 根据你的实际OAuth2授权类型调整OAuthFlows中的方法（比如密码模式用.password()）

内容的提问来源于stack exchange，提问作者Matt Campbell