SpringDoc OpenAPI OAuth2资源服务器异常：授权成功后API返回401

以下是排查和解决的关键点：

1. 确保接口关联了定义的SecurityScheme #

在需要授权访问的接口方法或Controller类上添加@SecurityRequirement(name = "security_auth")注解——你在OpenApiConfig中定义的SecurityScheme名称是security_auth，只有关联后Swagger UI才会自动携带授权token调用接口：

@RestController
@SecurityRequirement(name = "security_auth")
public class UserController {
    // 接口方法
}

2. 验证权限范围（Scope）匹配 #

• 检查OpenApiConfig中定义的scopes（trust/read/write），确认获取token时请求的scope包含接口所需权限。比如接口需要read权限，但获取token时未指定该scope，会导致401。
• 在Swagger UI的授权弹窗中，确保勾选了对应的权限范围，未勾选的话token不会包含该scope。

3. 修正Swagger UI的OAuth配置（针对密码模式） #

你在OpenApiConfig中使用的是密码模式（password flow），但application.yml中配置的use-basic-authentication-with-access-code-grant是针对授权码模式的，密码模式不需要该配置，建议修改：

springdoc:
  version: 'v1.0'
  swagger-ui:
    oauth:
      use-pkce-with-authorization-code-grant: false # 密码模式不需要PKCE
      client-id: USER_CLIENT_APP
      client-secret: password
  oAuthFlow:
    authorizationUrl: ${OAUTH2_SERVER:http://localhost:8080}/oauth/authorize
    tokenUrl: ${OAUTH2_SERVER:http://localhost:8080}/oauth/token

同时，在Swagger授权时，确认弹窗中输入了正确的用户名和密码（密码模式需要用户凭证）。

4. 手动验证token有效性 #

用Postman获取的token，在Swagger UI中选择Bearer Token方式手动粘贴token，调用接口测试：

• 如果能正常访问，说明Swagger自动携带token的流程存在问题，需检查授权配置；
• 如果仍返回401，说明token本身无效，或Spring Security的权限配置限制了该用户访问接口，需检查OAuth2服务器的token生成逻辑、接口的权限拦截规则。

5. 检查版本兼容性 #

确保springdoc-openapi的版本与你的Spring Boot、Spring Security OAuth2版本兼容：

• Spring Boot 2.x对应springdoc-openapi-ui 1.x版本；
• Spring Boot 3.x对应springdoc-openapi-starter-webmvc-ui 3.x版本。

内容的提问来源于stack exchange，提问作者Minh Trần