swagger OpenAPI 3.x.x随着可选参数的变化而具有不同的响应

我正在尝试为现有的API创建OAS Swagger文档，其中API的响应基于查询参数而更改。我正在努力以开发人员友好的方式记录这一点，所以需要一些帮助。下面是完整的场景供您参考。

终点1：/订单？expand=false

/order?expand=false

{
    "orderNo": "12345",
    "orderDetail": "Description of Order",
    "orderMarket": {
        "id": "UK"
    },
    "brandOrderStatus": {
        "id": "LLA"
    }
}

端点2：/订单？expand=true

{
    "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"
    }
}

端点3：/订单？expand=true&include=feature

{
    "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"
            }
        ]
    }
}

我尝试使用OneOf，但并不真的认为在这种情况下会工作，因为结构会随着每个可选参数而变化。
有什么想法可以记录在Swagger文档中吗？或者其他什么方法来记录这一切。

最直接的解决方案取决于您期望如何使用OpenAPI描述。如果仅用于文档目的，则可以使用examples并相应地定义它们。如果您想将其用于代码生成，使用anyOf可能是定义预期有效负载的更好选择。
不幸的是，OpenAPI没有一个很好的方法来记录这样的“场景”。（如果我发送这些查询参数，这就是响应）。没有一个examples明确对应于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"
              }
            ]
          }
        }
      }
    }
  }
}

swagger OpenAPI 3.x.x随着可选参数的变化而具有不同的响应

1条答案

相关问题

热门标签

最新问答