Swagger UI 将参数标记为组答案

【问题标题】：Swagger UI marking parameters as groupSwagger UI 将参数标记为组
【发布时间】：2018-07-12 11:19:33
【问题描述】：

是否可以以某种方式标记属性，以便在发送请求时在 SwaggerUI 中设置哪个字段是可以理解的。

例如，我们有一个支付路径，它具有 payment_type 属性，可以保存诸如 paypal、credit_card 之类的值strong>、crypto 等，基于该字段，我们需要填充不同的属性，如下所示。

{
  "payment": 0,
  "paypal": "test@test.com",
  "cryptocurrency": "test",
  "wallet_address": "test",
  "swift": "test",
  "iban": "test",
  "account_name": "test",
  "bank_name": "test"
}

是否可以以某种方式标记它们以便将它们分组，例如 crypto cryptocurrency 和 wallet_address应该设置，而对于 银行转帐 swift、iban、account_name 和 bank_name。

【问题讨论】：

Swagger: variant schema shape dependant on field value 的可能重复项。相关：Swagger Inheritance and Composition、“discriminator” in polymorphism, OpenAPI 2.0 (Swagger 2.0)、OpenAPI documentation for a single endpoint multiple posts request
您能否提供一个使用此模型的最小 swagger 定义？我想尝试合并@Helen 在 cmets 中提到的内容......让我们看看这是否可以理解发送请求时应该在 SwaggerUI 中设置哪个字段。

标签： swagger swagger-ui swagger-2.0

【解决方案1】：

不，没有这样的选择。我们受限于OpenAPI-Specification，请阅读参数对象部分以查看可用字段列表。

现在知道限制并非一切都会丢失，这里有一些选择：

您确实有 description，这是添加您的详细信息的好地方。
你也可以使用Specification Extension，但这不是 swagger-ui 默认支持的，如果你需要 UI 对你的扩展采取行动，你需要编码它。
@Helen 在 cmets 中指出的另一个选项是使用 discriminator，但 swagger-ui 目前不支持：
https://github.com/swagger-api/swagger-ui/issues/2438

【讨论】：

there is no such an option - 实际上discriminator 可以用于这种场景，如explained here。
@helen 是否可以用于平面结构或仅用于对象？
@Helen 感谢有关discriminator 的提示，我个人以前从未使用过它...而且我正在努力创建一个满足问题的示例：> 如何使其可以理解哪个字段应该发送请求时在 SwaggerUI 中设置？
@DoubleK: discriminator 适用于“平面”对象，可能也适用于嵌套对象，具体取决于用例 - 例如模型继承/组合使您可以更改顶级属性，但可能不能更改嵌套属性。查看链接问题中的example - 它与您的情况非常相似，只是属性名称不同。
@HelderSepu "发送请求时，如何让 SwaggerUI 中设置哪个字段易于理解？" 好问题。您可以在 API 定义中定义 discriminator 和模型继承/组合，但 Swagger UI 目前 does not support 基于 discriminator 切换输入模型。 This answer 提到了一个支持 discriminator 的替代文档渲染器 - 如果这是一个选项。