Swagger - 带有 form-urlEncoded 项的 Formdata

Question

我正在尝试为我的 api 创建一个 swagger 文档，但我有点卡住了一些我认为一旦你知道如何就很容易实现的东西。

我有一个端点，它接受作为 multipart/form-data 的帖子（因为它需要上传文件），但是其中一项（假装它在本示例中称为“carParts”）是 FormURLEncodedContent 类型这是一个键/值对列表。

所以结构是这样的：

汽车名称：福特
车龄：20
carParts:wheels=4&horn=true&windscreen=broken

我的问题是我不确定如何在 swagger 文档中表达这个（“carParts”）。

我能看到的唯一方法是将“carParts”项目设置为字符串类型，但随后我失去了招摇的意义，因为我想要“轮子”、“喇叭”和“挡风玻璃”是显式字段，而不仅仅是单个 form-urlEncoded 字符串。

用swagger可以做到这一点吗？

如果不是，我想唯一的其他选择是将我的 api 更改为仅将“carParts”项目作为平面列表而不是结构（即失去“carParts”父级别并让项目只是其他顶部级表单数据项）。 这似乎是最直接的方式，但如果我需要修改 api 来实现这一点，那就太可惜了（不是主要问题，只是感觉不对）。

Answer 1

这在 OpenAPI 3.0 中是可能的，但在 OpenAPI/Swagger 2.0 中是不可能的。

在 OpenAPI/Swagger 2.0 中，表单字段不能是对象，因此您必须将 carParts 定义为字符串或原语数组。

在 OpenAPI 3.0 中，您可以在表单字段中包含对象，并且您可以指定这些对象的序列化方式。目前例子不多，但我觉得你的情况可以这样描述：

paths:
  /something:
    post:
      requestBody:
        required: true
        content:

          multipart/form-data:
            # Form fields (carName, etc.) are defined as object properties
            schema:
              type: object
              properties:
                carName:
                  type: string
                carAge:
                  type: string
                carParts:
                  type: object
                  properties:
                    wheels:
                      type: integer
                    horn:
                      type: boolean
                    windscreen:
                      type: string
            # By default, the "carParts" object will be serialized as application/json,
            # but we can override the serialization method to be form-urlencoded
            encoding:
              carParts:
                contentType: application/x-www-form-urlencoded

规范的相关部分：Special Considerations for multipart Content。