PolymorphicProxySerializer 中 oneOf 值的详解指南：如何为多态响应生成准确的 OpenAPI 模式？

DRF PolymorphicProxySerializer 中的 oneOf 值：深入解析

概述

在使用 Django REST Framework（DRF）的 Spectacular 插件生成 OpenAPI 模式时，PolymorphicProxySerializer 可以为多态响应创建复杂的模式。然而，在处理根据不同状态返回不同响应的视图时，生成正确的 oneOf 值至关重要。

问题

当使用 PolymorphicProxySerializer 为端点定义模式时，我们面临一个问题，生成的模式中 oneOf 字段为空。这表明 DRF 无法识别用于表示不同响应类型的内联序列化程序。

解决方案

要解决此问题，我们需要指定 resource_type_mapping 参数。该参数将内联序列化程序名称与其关联的资源类型映射起来。通过提供此映射，DRF 现在可以将内联序列化程序添加到 oneOf 字段中。

修改后的代码如下：

device_service_get_schema = extend_schema_view(
    get=extend_schema(
        responses={
            200: PolymorphicProxySerializer(
                resource_type_field_name="timestamp",
                serializers=[
                    inline_serializer(
                        name="DeviceServiceFailurePayload",
                        fields={
                            "timestamp": OpenApiTypes.NONE,
                            "message": OpenApiTypes.STR,
                        },
                    ),
                    inline_serializer(
                        name="DeviceServiceSuccessPayload",
                        fields={
                            "timestamp": OpenApiTypes.DATETIME,
                            "devices": OpenApiTypes.OBJECT,
                        },
                    ),
                ],
                resource_type_mapping={
                    "DeviceServiceFailurePayload": "failure",
                    "DeviceServiceSuccessPayload": "success",
                },
            )
        },
    )
)

生成模式

添加 resource_type_mapping 后，生成的模式将正确包含 oneOf 值：

    MetaDeviceService:
      oneOf:
      - $ref: '#/components/schemas/DeviceServiceFailurePayload'
      - $ref: '#/components/schemas/DeviceServiceSuccessPayload'
      discriminator:
        propertyName: timestamp
        mapping:
          failure: DeviceServiceFailurePayload
          success: DeviceServiceSuccessPayload

结论

通过使用 resource_type_mapping 参数，我们能够在 DRF PolymorphicProxySerializer 中正确生成 oneOf 值。这确保了 OpenAPI 模式准确地反映了视图的响应结构。

常见问题解答

1. 什么是 oneOf 值？
   oneOf 值是在 OpenAPI 模式中表示多态响应的不同选项。
2. 为什么 resource_type_mapping 很重要？
   resource_type_mapping 将内联序列化程序名称与其关联的资源类型映射起来，以便 DRF 可以正确识别它们。
3. 如何使用 resource_type_mapping？
   在 PolymorphicProxySerializer 中指定 resource_type_mapping 参数，其中包含内联序列化程序名称与其资源类型之间的映射。
4. oneOf 值对 OpenAPI 模式有什么好处？
   oneOf 值为客户端提供不同响应选项的清晰视图，从而提高 API 可用性。
5. 我可以自定义 oneOf 值的名称吗？
   不可以，oneOf 值的名称是由 DRF 根据 resource_type_field_name 自动生成的。