如何在drf_spectacular中为所有URL路径添加全局请求头参数？

方法1：使用DEFAULT_PARAMETERS全局配置（最简便） #

直接在settings.py的SPECTACULAR_SETTINGS中配置全局默认参数，所有API视图会自动继承这个参数，无需在每个视图重复编写代码：

# settings.py
from drf_spectacular.openapi import OpenApiParameter

SPECTACULAR_SETTINGS = {
    # 保留你原有其他配置
    'DEFAULT_PARAMETERS': [
        OpenApiParameter(
            name='accept-language',
            type=str,
            location=OpenApiParameter.HEADER,
            description="fa or en. The default value is en"
        ),
    ],
}

方法2：自定义Schema生成器（灵活控制范围） #

如果需要给特定视图而非全部视图添加该参数，可以自定义Schema生成器，通过逻辑判断实现精准控制：

# 项目根目录新建schema.py
from drf_spectacular.generators import SpectacularJSONSchemaGenerator
from drf_spectacular.openapi import OpenApiParameter
from rest_framework.views import APIView

class CustomSchemaGenerator(SpectacularJSONSchemaGenerator):
    def get_operation_parameters(self, operation):
        params = super().get_operation_parameters(operation)
        # 示例：仅给APIView的子类添加该参数
        if isinstance(operation.view, APIView):
            params.append(
                OpenApiParameter(
                    name='accept-language',
                    type=str,
                    location=OpenApiParameter.HEADER,
                    description="fa or en. The default value is en"
                )
            )
        return params

然后在settings.py中指定自定义生成器：

# settings.py
SPECTACULAR_SETTINGS = {
    # 保留其他配置
    'SCHEMA_GENERATOR_CLASS': 'your_project_name.schema.CustomSchemaGenerator',
}

方法3：使用预处理钩子（全局批量修改） #

通过预处理钩子在Schema生成完成前，给所有操作批量添加参数：

# settings.py
def add_global_header(schema, request, public):
    # 遍历所有路径下的API操作
    for path in schema.get('paths', {}).values():
        for operation in path.values():
            # 给当前操作追加header参数
            operation.setdefault('parameters', []).append({
                'name': 'accept-language',
                'in': 'header',
                'description': "fa or en. The default value is en",
                'required': False,
                'schema': {'type': 'string'}
            })
    return schema

SPECTACULAR_SETTINGS = {
    # 保留其他配置
    'PREPROCESSING_HOOKS': [
        'your_project_name.settings.add_global_header',
    ],
}

关于APPEND_COMPONENTS的用法说明 #

这个配置是用来定义可复用的OpenAPI组件，而非直接全局自动添加参数。适合需要在部分视图复用参数的场景，示例如下：

# settings.py
SPECTACULAR_SETTINGS = {
    # 保留其他配置
    'APPEND_COMPONENTS': {
        'parameters': {
            'AcceptLanguageHeader': {
                'name': 'accept-language',
                'in': 'header',
                'description': "fa or en. The default value is en",
                'required': False,
                'schema': {'type': 'string'}
            }
        }
    },
}

之后在视图中只需引用组件即可，不用重复写完整参数定义：

@extend_schema(parameters=['#/components/parameters/AcceptLanguageHeader'])
class YourView(APIView):
    # 视图逻辑

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