OpenApi 3.0.1 中的互斥对象

Question

我正在尝试创建一个 OpenAPI 3.0.1 合约，我想在请求模式中创建两个互斥的 JSON 对象。例如：

"grandparent": {
    "parent": {
        "child1": {
            "grandChild1": "string"
        },
        "child2": {
            "grandChild3": "string"
        },
        "child3": {
            "grandChild3": "string"
        },
        "child4": {
            "grandChild4": "string"
        }
    }
}

在示例中，如何创建合约以使 child3 和 child4 不能在请求中共存。如果收到这样的请求，我的 Swagger Codegen 应该能够生成 400 Bad Request。我尝试使用 oneOf 来解决这种情况，但我不确定是否可以使用。

{
    "openapi": "3.0.3",
    "info": {
        "title": "Example API with Grandparents",
        "version": "1.0.0"
    },
    "paths": {
        "/example": {
            "post": {
                "summary": "Endpoint with mutually exclusive objects under grandparent",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "grandparent": {
                                        "type": "object",
                                        "properties": {
                                            "parent": {
                                                "type": "object",
                                                "properties": {
                                                    "child1": {
                                                        "type": "object",
                                                        "properties": {
                                                            "grandChild1": {
                                                                "$ref": "#/components/schemas/GrandChild1"
                                                            }
                                                        }
                                                    },
                                                    "child2": {
                                                        "type": "object",
                                                        "properties": {
                                                            "grandChild2": {
                                                                "$ref": "#/components/schemas/GrandChild2"
                                                            }
                                                        }
                                                    },
                                                    "oneOf": [{
                                                            "type": "object",
                                                            "properties": {
                                                                "child3": {
                                                                    "type": "object",
                                                                    "properties": {
                                                                        "grandChild3": {
                                                                            "$ref": "#/components/schemas/GrandChild3"
                                                                        }
                                                                    }
                                                                }
                                                            },
                                                            "required": ["child3"]
                                                        }, {
                                                            "type": "object",
                                                            "properties": {
                                                                "child4": {
                                                                    "type": "object",
                                                                    "properties": {
                                                                        "grandChild4": {
                                                                            "$ref": "#/components/schemas/GrandChild4"
                                                                        }
                                                                    }
                                                                }
                                                            },
                                                            "required": ["child4"]
                                                        }
                                                    ]
                                                }
                                            }
                                        },
                                        "required": ["grandparent"]
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Success"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "GrandChild1": {
                "type": "string",
                "maxLength": 36
            },
            "GrandChild2": {
                "type": "string",
                "maxLength": 36
            },
            "GrandChild3": {
                "type": "string",
                "maxLength": 36
            },
            "GrandChild4": {
                "type": "string",
                "maxLength": 36
            },
        }
    }
}

Answer 1

编写模式的方式是使

oneOf

成为属性名称，而不是验证约束。

oneOf

应该是

properties

关键字

的兄弟

使用 OpenAPI 3.0.x 使用的 JSON Schema Draft-04，您需要将

oneOf

的兄弟属性重新定义到每个子模式中，并使用

additionalProperties: false

来约束互斥属性的使用。用空模式重新定义这些关键字就足够了。

{
    "type": "object",
    "properties": {
        "child1": {
            "type": "object",
            "properties": {
                "grandChild1": {
                    "$ref": "#/components/schemas/GrandChild1"
                }
            }
        },
        "child2": {
            "type": "object",
            "properties": {
                "grandChild2": {
                    "$ref": "#/components/schemas/GrandChild2"
                }
            }
        }
    },
    "oneOf": [
        {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "child1": {},
                "child2": {},
                "child3": {
                    "type": "object",
                    "properties": {
                        "grandChild3": {
                            "$ref": "#/components/schemas/GrandChild3"
                        }
                    }
                }
            },
            "required": [
                "child3"
            ]
        },
        {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "child1": {},
                "child2": {},
                "child4": {
                    "type": "object",
                    "properties": {
                        "grandChild4": {
                            "$ref": "#/components/schemas/GrandChild4"
                        }
                    }
                }
            },
            "required": [
                "child4"
            ]
        }
    ]
}