Swagger - Formdata与一个表单urlEncoded项目

Question

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

我有一个接受post作为multipart/form-data（因为它需要文件上传），但其中的一个项目（假设它被称为“carParts”为了这个例子）是一个FormURLEncodedContent键入的是键/值对的列表。

所以结构是一样的东西：

carName：福特
carAge：20
carParts：车轮= 4 &角=真&挡风玻璃=破

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

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

是否有可能这样做与大招？

如果不是，我想唯一的其他选择是将我的api更改为仅将“carParts”项目作为扁平列表而不是结构（即失去“carParts”父级并使项目仅为其他顶级formdata项目）。 这似乎是最直接的方式，但如果我需要修改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。