对于此类问题，最直接的解决方案取决于您期望如何使用 OpenAPI 描述。如果仅用于文档目的，您可以使用examples并相应地定义它们。如果您想将其用于代码生成，请使用anyOf可能是定义预期有效负载的更好选择。
不幸的是，OpenAPI 没有一个很好的方法来记录这样的“场景”。 （如果我发送这些查询参数，这就是响应）。没有任何一个examples将明确对应于anyOf模式表示。您需要使用完整表示或使用anyOf架构设计。
这是示例和 anyOf 响应模式
{
"openapi": "3.0.3",
"info": {
"title": "test",
"version": "1.0.0"
},
"servers": [],
"paths": {
"/order": {
"get": {
"summary": "stack",
"parameters": [
{
"$ref": "#/components/parameters/expand"
},
{
"$ref": "#/components/parameters/include"
}
],
"responses": {
"200": {
"description": "OK",
"headers": {},
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/order"
},
{
"$ref": "#/components/schemas/orderDetail"
},
{
"$ref": "#/components/schemas/orderDetailWithFeatures"
}
]
},
"examples": {
"expand_false": {
"$ref": "#/components/examples/expand_false"
},
"expand_true": {
"$ref": "#/components/examples/expand_true"
},
"expand_with_features": {
"$ref": "#/components/examples/expand_with_features"
}
}
}
}
}
}
}
}
},
"components": {
"parameters": {
"expand": {
"name": "expand",
"description": "expands the response schema with more details",
"in": "query",
"schema": {
"type": "boolean"
}
},
"include": {
"name": "include",
"description": "expands the response schema with more details",
"in": "query",
"schema": {
"type": "string",
"enum": [
"feature"
]
}
}
},
"schemas": {
"order": {
"type": "object",
"properties": {
"orderNo": {
"type": "string"
},
"orderDetail": {
"type": "string"
},
"orderMarket": {
"type": "object",
"properties": {
"id": {
"type": "string"
}
}
},
"brandOrderStatus": {
"type": "object",
"properties": {
"id": {
"type": "string"
}
}
}
}
},
"amountType": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"amount": {
"type": "number"
},
"currency": {
"type": "string",
"enum": [
"USD",
"GBP",
"EUR"
]
}
}
},
"lang-descType": {
"type": "object",
"properties": {
"lang": {
"type": "string"
},
"descr": {
"type": "string"
}
}
},
"features": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string"
},
"descr": {
"type": "string"
},
"prices": {
"type": "array",
"items": {
"$ref": "#/components/schemas/amountType"
}
},
"group": {
"type": "string"
}
}
}
},
"orderDetail": {
"allOf": [
{
"$ref": "#/components/schemas/order"
},
{
"type": "object",
"properties": {
"orderMarket": {
"allOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string"
}
}
},
{
"$ref": "#/components/schemas/lang-descType"
}
]
},
"brandOrderStatus": {
"allOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string"
}
}
},
{
"$ref": "#/components/schemas/lang-descType"
}
]
}
}
}
]
},
"orderDetailWithFeatures": {
"allOf": [
{
"$ref": "#/components/schemas/orderDetail"
},
{
"type": "object",
"properties": {
"_embedded": {
"type": "object",
"properties": {
"features": {
"type": "array",
"items": {
"$ref": "#/components/schemas/features"
}
}
}
}
}
}
]
}
},
"examples": {
"expand_false": {
"value": {
"orderNo": "12345",
"orderDetail": "Description of Order",
"orderMarket": {
"id": "UK"
},
"brandOrderStatus": {
"id": "LLA"
}
}
},
"expand_true": {
"value": {
"orderNo": "12345",
"orderDetail": "Description of Order",
"orderMarket": {
"id": "UK",
"descr": "United Kingdom",
"lang": "en-GB"
},
"brandOrderStatus": {
"id": "LLA",
"descr": "Some Status Description",
"lang": "en-GB"
}
}
},
"expand_with_features": {
"value": {
"orderNo": "12345",
"orderDetail": "Description of Order",
"orderMarket": {
"id": "UK",
"descr": "United Kingdom",
"lang": "en-GB"
},
"brandOrderStatus": {
"id": "LLA",
"descr": "Some Status Description",
"lang": "en-GB"
},
"_embedded": {
"features": [
{
"id": "AJS",
"type": "FeatureType",
"descr": "FeatureDescription",
"prices": [
{
"type": "msrpNetPrice",
"amount": 0.00,
"currency": "GBP"
}
],
"group": "null"
}
]
}
}
}
}
}
}
