Question

我试图为我的api创建一个昂首阔步的文档，而且我知道如果你知道如何，我会想到很容易实现的东西。

我有一个端点接受一个帖子作为multipart / form-data（因为它需要一个文件上传），但是其中一个项目（假装它被称为＆＃34; carParts＆＃34;为了这个缘故这个示例）是FormURLEncodedContent类型，它是键/值对的列表。

所以结构类似于：

carName：福特
carAge：20
carParts：车轮= 4和;喇叭=真安培;挡风玻璃=破

我的问题是，我不确定如何在招摇文件中表达这一点（＆＃34; carParts＆＃34;）。

我能看到的唯一方法是设置＆＃34; carParts＆＃34;项目为字符串类型，但后来我失去了招摇的点，因为我想要＆＃34;轮子＆＃34;，＆＃34;号角＆＃34;和＆＃34;挡风玻璃＆＃34;是显式字段，而不仅仅是一个form-urlEncoded字符串。

是否可以通过招摇来做到这一点？

如果没有，我想唯一的另一个选择就是改变我的api，只需拥有＆＃34; carParts＆＃34;作为平面列表而不是结构的项目（即丢失＆＃34; carParts＆＃34;父级别，并且项目只是其他顶级形式数据项目）。这似乎是最直接的方式，但如果我需要修改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 - Formdata with form-urlEncoded Item

1 个答案: