Question

我正在尝试使用OpenAPI 3建立来自各种架构组件的响应。响应基本上包括三个部分：

其他端点使用的共享组件（即成功/失败标志）。 -#/components/schemas/core_response_schema内的allOf。
此端点上所有个响应使用的属性（即user_id）-以下内容的properties组件。
根据用户类型而有所不同的几种模式之一。 -oneOf组件。

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

以下内容成功传递了三种不同的OpenAPI整理工具，但在构建的示例中，Swagger UI并未显示项目2的内容（属性），而确实显示了项目3的所有内容（应该是一个）。

"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的情况下将模式与属性混合？

这表明可能：Swagger Schema: oneOf, anyOf, allOf valid at the same time?

Answer 1

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

就至少三种不同的整理工具而言，anyOf，oneOf和allOf的混合可以在同一模式中一起使用。

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

构建一个OpenAPI响应，包括oneOf，也许包括allOf

1 个答案: