如何在DRF Spectacular中预填充认证字段及解决Request Name异常

解决步骤： #

1. 修正类名拼写错误
   你的扩展类中target_class存在拼写错误：KeycloackBasicAuth → KeycloakBasicAuth（少了一个字母a），这会导致DRF Spectacular无法匹配到你的认证类，扩展逻辑不会生效。修正后：

   class KeycloakBasicAuthExtension(OpenApiAuthenticationExtension):
       target_class = "contrib.keycloak.auth.KeycloakBasicAuth"  # 修正拼写
       name = "Basic Auth"
       priority = 1
       match_subclasses = True
   
       def get_security_definition(self, auto_schema):
           return {
               "type": "http",
               "scheme": "basic",
               "x-example": {"username": "test", "password": "test"},
           }
   

2. 注册认证扩展
   必须将扩展添加到DRF Spectacular的配置中，否则框架不会加载它。在项目settings.py中添加：

   SPECTACULAR_SETTINGS = {
       # 其他配置...
       "AUTHENTICATION_EXTENSIONS": [
           "path.to.your.module.KeycloakBasicAuthExtension",  # 替换为实际路径
       ],
   }
   

3. 适配Gitbook渲染逻辑
   如果Gitbook仍不显示示例，可尝试在接口操作中添加包含Basic Auth头的请求示例：

   "examples": [
       OpenApiExample(
           "Create Payment Transaction with Basic Auth",
           summary="带Basic Auth的请求示例",
           description="包含预填充用户名密码的请求示例",
           value={
               "amount": "1.000",
               "currency_code": "KWD",
               "pg_codes": get_default_pg_codes(),
               "type": "payment_request",
           },
           request_only=True,
           headers={"Authorization": "Basic dGVzdDp0ZXN0"},  # base64编码的test:test
       ),
   ]
   

解决步骤： #

1. 显式设置序列化器的Schema标题
   在你的请求序列化器类中，通过Meta类指定schema_title，确保Gitbook能识别到名称：

   class CheckoutPOSTRequestSerializer(serializers.Serializer):
       amount = serializers.CharField()
       currency_code = serializers.CharField()
       # 其他字段...
   
       class Meta:
           schema_title = "CheckoutPOSTRequestSerializer"
   

2. 使用OpenApiRequestBody包装请求序列化器
   在Schema配置中，用OpenApiRequestBody显式声明请求体的名称和描述，替代直接传入序列化器：

   from drf_spectacular.utils import OpenApiRequestBody
   
   post = {
       # 其他配置...
       "request": OpenApiRequestBody(
           request=get_checkout_serializer(),
           name="CheckoutPOSTRequestSerializer",
           description="创建支付交易的请求体结构"
       ),
       # 其他配置...
   }
   

3. 验证OpenAPI Schema输出
   生成OpenAPI文档后，检查components/schemas下是否存在CheckoutPOSTRequestSerializer条目，确认其title字段正确设置。如果缺失，说明序列化器的名称未被正确注册，需检查get_checkout_serializer函数的实现逻辑。

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