构建 OpenAPI 响应，包括 oneOf，可能还有 allOf

Question

我正在尝试使用 OpenAPI 3 从各种模式组件构建响应。响应基本上分为三个部分：

其他端点使用的共享组件（即 success/failure 标志）。 - #/components/schemas/core_response_schema 里面 allOf.
此端点上的所有响应使用的属性（即user_id）-下面的properties组件。
根据用户类型而变化的几种模式之一。 - oneOf 组件。

我确定我必须使用 allOf 才能混合属性（第 2 项）和核心响应（第 1 项），尽管这感觉不对，因为只有一项。我试了 $ref，但没用。

下面成功地通过了三种不同的 OpenAPI linting 工具，但在它构建的示例中，Swagger UI 不显示项目 2 的东西（属性），而会显示所有项目 3 的东西（应该是 oneOf）。

"responses": {
    "200": {
        "description": "Operation successfully executed.",
        "content": {
            "application/json": {
                "schema": {
                    "properties": {
                        "user_id": {
                            "$ref": "#/components/schemas/user_id"
                        },
                        "results": {
                            "type": "array",
                            "items": {
                                "$ref": "#/components/schemas/result_user_by_id"
                            }
                        }
                    },
                    "type": "object",
                    "allOf": [
                        {
                            "$ref": "#/components/schemas/core_response_schema"
                        }
                    ],
                    "oneOf": [
                        {
                            "$ref": "#/components/schemas/user_type_a"
                        },
                        {
                            "$ref": "#/components/schemas/user_type_b"
                        },
                        {
                            "$ref": "#/components/schemas/user_type_c"
                        }
                    ]
                }
            }
        }
    }
},
"components": {
    "schemas": {
        "core_response_schema": {
            "properties": {
                "success": {
                    "description": "A flag indicating whether the request was successfully completed or not.",
                    "type": "boolean"
                },
                "num_results": {
                    "description": "The number of results for this request",
                    "type": "integer"
                }
            },
            "type": "object"
        },
        "user_id": {
            "description": "Unique 10 character `user_id`.",
            "type": "string",
            "maxLength": 10,
            "minLength": 10,
            "example": "a1b2c3d4e5"
        },
    }
}

以及两个用户的示例负载。键入 A 和 B（这是一个人为的例子）。

用户类型 A：

{
    "success": true,
    "num_results": 1,
    "user_id": "c1b00cb714",
    "results": [{
            "user_type": "a",
            "group_id": "e7a99e3769",
            "name": null,
            "title": null,
            ... (and so on until we get to the stuff that's unique to this type of user) ...
            "favourite_artworks": [
                "sunflowers",
                "landscapes"
            ],
            "artwork_urls": [
                "http://sunflowers.example"
            ]
        }
    ]
}

用户类型 B：

{
    "success": true,
    "num_results": 1,
    "user_id": "c1b00cb715",
    "results": [{
            "user_type": "B",
            "group_id": "e7a99e3769",
            "name": null,
            "title": null,
            ... (and so on until we get to the stuff that's unique to this type of user) ...
            "supported_charities": [
                "UN Foundations"
            ],
            "charity_urls": [
                "http://www.un.int"
            ],
        }
    ]
}

在 OpenAPI 中合并不同模式和属性的正确方法是什么？这是对的吗，Swagger UI 无法处理它？

如何在不使用 allOf 的情况下将模式与属性混合？

这表明这是可能的：

Answer 1

经过进一步调查，我确定这是 swagger-ui - https://github.com/swagger-api/swagger-ui/issues/3803 - 他们根本不支持 oneOf（或 anyOf ) 当前。

就至少三种不同的 linting 工具而言，anyOf、oneOf 和 allOf 的混合可以在同一架构中一起使用。

Redoc 似乎有类似的问题 - https://github.com/Rebilly/ReDoc/issues/641

构建 OpenAPI 响应，包括 oneOf，可能还有 allOf

Building an OpenAPI response, including oneOf, and maybe allOf

swagger-ui

openapi