我正在尝试使用 OpenAPI 3 从各种架构组件构建响应。响应基本上分为三个部分:
- 其他端点使用的共享组件(即成功/失败标志)。 -
#/components/schemas/core_response_schema
inside allOf
.
- 属性all对此端点的响应使用(即
user_id
) - the properties
以下的组成部分。
- 根据用户类型而变化的几种模式之一。 - 这
oneOf
成分。
我决定我必须使用allOf
能够混合属性(第 2 项)和核心响应(第 1 项),尽管这感觉不对,因为只有一项。我尝试了一个$ref
,但没有成功。
下面成功地通过了三个不同的 OpenAPI linting 工具,但在它构建的示例中,Swagger UI 没有显示第 2 项内容(属性),并且does显示第 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
?
这表明这是可能的:Swagger Schema:oneOf、anyOf、allOf 同时有效? https://stackoverflow.com/questions/49604468/swagger-schema-oneof-anyof-allof-valid-at-the-same-time