Swagger

Question

我正在尝试为我的 api 创建一个 swagger 文档，但我有点卡住了，我想一旦你知道怎么做就很容易实现。

我有一个接受 post 作为 multipart/form-data 的端点（因为它需要文件上传），但是其中一个项目（假装它被称为 "carParts"此示例）是一个 FormURLEncodedContent 类型，它是 key/value 对的列表。

所以结构是这样的：

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

我的问题是我不确定如何在 swagger 文档中表达这个 ("carParts")。

我能看到的唯一方法是将 "carParts" 项设置为字符串类型，但我失去了招摇的意义，因为我想要 "wheels"、"horn" 和 "windscreen" 是显式字段，而不仅仅是单个 form-urlEncoded 字符串。

是否可以大摇大摆地做到这一点？

如果不是，我想唯一的其他选择是更改我的 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。

Swagger - 带有 form-urlEncoded 项目的 Formdata

Swagger - Formdata with a form-urlEncoded Item

multipartform-data

swagger-editor