如何在Swagger UI中调用/oauth/token端点生成access_token

参数预期值说明 #

你碰到的两类校验对应的参数值分别如下：

• 弹出的用户名密码输入框是OAuth2密码授权流要求的客户端凭证校验，就填你提到的固定值trusted-client（用户名）和secret（密码）即可，对应你curl请求里的Authorization: Basic xxxxxxxxxxxxx头的内容
• Swagger页面上显示的/oauth/token端点必填查询/表单参数就是你curl请求里携带的三个参数，取值规则：
  • grant_type：固定填password，对应你使用的密码授权流类型
  • username：填写业务系统的用户登录账号
  • password：填写对应账号的登录密码

你直接忽略必填参数点击Execute会一直加载，是因为缺少必填参数的请求不符合后端接口要求，后端未返回合法响应，Swagger就一直处于等待状态。

端点参数配置修改说明 #

分两种场景处理：

1. 不建议修改/oauth/token本身的必填参数规则
   这个端点是Spring Security OAuth2的标准实现，完全遵循OAuth2协议规范，强制要求的参数都是协议规定的必填项，修改后会破坏协议兼容性，你现有的Postman请求、自动化测试脚本都需要同步调整，成本很高。

2. 可以修改Swagger层的参数展示配置
   如果你是想简化用户操作，比如固定grant_type为password不需要用户手动填写，可以通过调整Swagger Docket配置实现，示例代码如下：

   @Bean
   public Docket api() {
       // 构造grant_type参数，设置默认值为password
       Parameter grantTypeParam = new ParameterBuilder()
               .name("grant_type")
               .modelRef(new ModelRef("string"))
               .parameterType("query")
               .required(true)
               .defaultValue("password")
               .build();
       
       return new Docket(DocumentationType.SWAGGER_2)
               .groupName("version 2")
               // 注入全局参数，自动填充grant_type默认值
               .globalOperationParameters(Collections.singletonList(grantTypeParam))
               // 原有配置保持不变
               .select()
               .apis(Predicates.not(RequestHandlerSelectors.basePackage("org.springframework.boot")))
               .paths(input -> PathSelectors.regex("/oauth/token").apply(input))
               .build()
               .apiInfo(this.apiInfo("2"))
               .securitySchemes(Arrays.asList(this.authTok(), this.apiKey()))
               .securityContexts(Arrays.asList(this.securityContext))
               .useDefaultResponseMessages(false);
   }
   

更优的Swagger OAuth2集成方案 #

你不需要手动把/oauth/token端点暴露到Swagger列表里，Swagger原生支持OAuth2密码授权流的自动授权，配置完成后用户直接点击页面右上角的Authorize按钮填写信息，就能自动获取token并给所有业务接口自动添加Authorization: bearer xxxx请求头，不需要手动复制粘贴token，核心配置示例如下：

private SecurityScheme oauth2SecurityScheme() {
    // 配置密码授权流的token获取地址
    GrantType passwordGrant = new ResourceOwnerPasswordCredentialsGrant("/oauth/token");
    return new OAuthBuilder()
            .name("OAuth2")
            .grantTypes(Collections.singletonList(passwordGrant))
            // 没有权限范围要求就填空列表
            .scopes(Collections.emptyList())
            .build();
}

把上面返回的SecurityScheme替换你原有securitySchemes配置里的对应项即可。

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