如何在drf-spectacular的extend_schema装饰器中添加引用参数

要让drf-spectacular生成$ref格式的引用参数而非内联格式，有两种可行方案：

方案一：给OpenApiParameter添加ref_name属性 #

直接在定义OpenApiParameter时指定ref_name，drf-spectacular会自动将该参数提取到#/components/parameters/组件中，并在接口的参数列表里生成引用：

from drf_spectacular.utils import OpenApiParameter, OpenApiTypes

headerParam = [
    OpenApiParameter(
        name='Accept-Language', 
        location=OpenApiParameter.HEADER,
        type=OpenApiTypes.STR,
        description='ISO 2 Letter Language Code',
        required=True,
        enum=['en', 'ar'],
        ref_name='Accept-Language'  # 指定引用名称
    ),
    OpenApiParameter(
        name='Accept', 
        location=OpenApiParameter.HEADER,
        type=OpenApiTypes.STR,
        description='Type of response you are expecting from API. i.e. (application/json)',
        required=True,
        default='application/json',
        ref_name='Accept'  # 指定引用名称
    ),
]

在视图中使用@extend_schema的方式不变：

from drf_spectacular.utils import extend_schema

@extend_schema(
    parameters=headerParam,
    responses={200: Response1, 400: errorresponse},
    tags=['User'],
)

生成的Schema会自动把两个Header参数存入components/parameters，并在接口的parameters里生成$ref引用。

方案二：全局注册参数组件 #

在项目的settings.py中，通过SPECTACULAR_SETTINGS全局注册参数组件，之后在视图中直接引用该组件的路径：

第一步：全局注册参数 #

# settings.py
SPECTACULAR_SETTINGS = {
    # 其他已有配置...
    'COMPONENTS': {
        'parameters': {
            'Accept': {
                'in': 'header',
                'name': 'Accept',
                'schema': {'type': 'string', 'default': 'application/json'},
                'description': 'Type of response you are expecting from API. i.e. (application/json)',
                'required': True
            },
            'Accept-Language': {
                'in': 'header',
                'name': 'Accept-Language',
                'schema': {'type': 'string', 'enum': ['en', 'ar']},
                'description': 'ISO 2 Letter Language Code',
                'required': True
            }
        }
    }
}

第二步：在视图中引用组件 #

from drf_spectacular.utils import extend_schema

@extend_schema(
    parameters=[
        {'$ref': '#/components/parameters/Accept'},
        {'$ref': '#/components/parameters/Accept-Language'}
    ],
    responses={200: Response1, 400: errorresponse},
    tags=['User'],
)

原代码内联的原因 #

你之前的代码未指定ref_name或全局注册组件，drf-spectacular默认会将参数直接内联到接口的参数列表中，而非生成可复用的组件引用。

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