如何在OpenApi Basic Auth注解中预设用户名实现Try it out免填认证信息

解决方案 #

OpenAPI 3.x 规范本身不支持在SecurityScheme注解中直接预设默认认证凭证，你可以根据自己的使用场景选择以下两种可行方案：

方案1：修改Swagger UI配置（最推荐，符合规范） #

Swagger UI 原生提供了预授权方法，可以直接在初始化配置中添加预设的basic auth凭证，用户打开文档时就会自动完成认证，无需手动填写：

• 如果你使用原生Swagger UI初始化，在初始化参数中添加onComplete回调即可：

SwaggerUIBundle({
  url: "你的openapi.json路径",
  dom_id: '#swagger-ui',
  // 其他原有配置保留
  onComplete: function () {
    // 参数依次为：安全方案名称、预设用户名、预设密码（空字符串即可）
    this.preauthorizeBasic('basicAuth', '你的生成好的用户名', '');
  }
})

• 如果你使用Laravel的DarkaOnLine/L5-Swagger等封装包，可直接在对应扩展配置文件中添加预授权配置：

// 以L5-Swagger的config/l5-swagger.php为例
'defaults' => [
    'ui' => [
        'preauthorize' => [
            'basic' => [
                'basicAuth' => [
                    'username' => '你的生成好的用户名',
                    'password' => '',
                ],
            ],
        ],
    ],
]

方案2：注解配置预设请求头（无需修改UI配置，变通方案） #

Basic auth的本质是将用户名:（密码为空时仅需用户名加英文冒号）做Base64编码后放入Authorization请求头，你可以直接在全局注解中添加默认请求头，实现自动填充：

1. 先计算你的凭证编码：将你的用户名:做Base64编码，例如用户名为demo时，demo:的Base64编码结果为ZGVtbzo=
2. 修改你的OpenAPI注解，添加全局请求头配置：

/**
 * @OA\OpenApi(
 *    security={{"basicAuth": {}}},
 *    @OA\Parameter(
 *        name="Authorization",
 *        in="header",
 *        required=false,
 *        @OA\Schema(type="string", default="Basic ZGVtbzo="),
 *        description="基础认证凭证，已默认填充"
 *    )
 * )
 *
 * @OA\Components(
 *     @OA\SecurityScheme(
 *         securityScheme="basicAuth",
 *         type="http",
 *         scheme="basic",
 *     )
 * )
 */

该方案无需修改Swagger UI配置即可生效，缺点是Authorization头会直接显示在参数列表中，而非走标准的安全认证弹窗流程。

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