如何在drf-spectacular的OpenApiParameter中指定OBJECT类型属性？

在drf-yasg里可以通过properties参数直接定义OBJECT类型的嵌套字段，在drf-spectacular中可以用以下方式实现相同效果：

方式1：定义请求体为OBJECT类型 #

如果是要把OBJECT作为请求体（对应原代码的request参数场景），使用extend_schema装饰器搭配OpenApiSchema构建结构，写法和drf-yasg非常相似：

from drf_spectacular.utils import extend_schema, OpenApiSchema, OpenApiTypes

@extend_schema(
    summary="钱包余额",
    description="保存钱包的余额数据",
    request=OpenApiSchema(
        type=OpenApiTypes.OBJECT,
        properties={
            'balance': OpenApiSchema(type=OpenApiTypes.NUMBER),
            'some_object': OpenApiSchema(
                type=OpenApiTypes.OBJECT,
                properties={
                    'a': OpenApiSchema(type=OpenApiTypes.STRING),
                    'b': OpenApiSchema(type=OpenApiTypes.STRING),
                }
            ),
        }
    )
)
def save_wallet_balance(request):
    # 这里写视图逻辑
    pass

方式2：定义查询参数为OBJECT类型 #

如果是要把OBJECT作为查询参数（而非请求体），则通过OpenApiParameter来定义，指定类型为OBJECT并配置properties：

from drf_spectacular.utils import extend_schema, OpenApiParameter, OpenApiSchema, OpenApiTypes

@extend_schema(
    summary="钱包余额",
    description="查询钱包余额",
    parameters=[
        OpenApiParameter(
            name='wallet_info',
            type=OpenApiTypes.OBJECT,
            properties={
                'balance': OpenApiSchema(type=OpenApiTypes.NUMBER),
                'some_object': OpenApiSchema(
                    type=OpenApiTypes.OBJECT,
                    properties={
                        'a': OpenApiSchema(type=OpenApiTypes.STRING),
                        'b': OpenApiSchema(type=OpenApiTypes.STRING),
                    }
                )
            },
            location=OpenApiParameter.QUERY,
            description='钱包相关信息参数'
        )
    ]
)
def get_wallet_balance(request):
    # 这里写视图逻辑
    pass

关键注意点 #

• drf-spectacular用extend_schema替代drf-yasg的swagger_auto_schema
• 类型常量从openapi.TYPE_*替换为OpenApiTypes.*
• 嵌套OBJECT字段的核心逻辑和drf-yasg一致，都是通过properties字段定义子结构

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