构建OpenAPI响应，包括其中之一，也可能包括Allof [英] Building an OpenAPI response, including oneOf, and maybe allOf

问题描述

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

1. 其他终结点使用的共享组件(即成功/失败标志)。-#/components/schemas/core_response_schema内部allOf。
2. 此终结点上的所有响应使用的属性(即user_id)-以下的properties组件。
3. 根据用户类型的不同而不同的几个架构之一。-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?

推荐答案

进一步调查后，我确定这是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响应，包括其中之一，也可能包括Allof的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！