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。