如何使用 OpenAPI 3 在 multipart/form-data 請求的請求正文中格式化 JSON 數組？

Question

我正在嘗試為現有端點編寫 OpenAPI 3 規范。 端點使用multipart/form-data Content-Type ，其中一個參數接受 JSON 數組字符串。 以下 curl 顯示了此端點正常工作的示例：

curl -X 'POST' \
  'https://testing.org/test/' \
  -H 'accept: */*' \
  -H 'Content-Type: multipart/form-data' \
  -F 'simple=abc' \
  -F 'complex=[{"key": "string", "size": 0}"]'

我的 OpenAPI 3 規范目前如下所示：

openapi: 3.0.3
info:
  title: Simple
  description: Testing
  version: '1.0'
servers:
  - url: 'https://testing.org'
paths:
  /test/:
    post:
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                simple: 
                  type: string
                complex:
                  type: array
                  items:
                      type: object
                      properties:
                        key: 
                          type: string
                        size: 
                          type: integer
            encoding:
              complex:
                contentType: application/json
      responses:
        '200':
          description: OK

但是，在swagger 編輯器中使用“test it out”功能會產生如下所示的請求：

curl -X 'POST' \
  'https://testing.org/test/' \
  -H 'accept: */*' \
  -H 'Content-Type: multipart/form-data' \
  -F 'simple=abc' \
  -F 'complex=["{\n  \"key\": \"string\",\n  \"size\": 0\n}"]'

complex參數的格式不正確。 如果我刪除了規范的encoding部分，這就是請求的樣子：

curl -X 'POST' \
  'https://testing.org/test/' \
  -H 'accept: */*' \
  -H 'Content-Type: multipart/form-data' \
  -F 'simple=abc' \
  -F 'complex={
  "key": "string",
  "size": 0
}'

這是一個 JSON 對象，但不是一個 JSON 數組。

關於如何格式化 OpenAPI 3 規范以便將complex表單參數格式化為一個簡單的 JSON 數組[{"key": "string", "size": 0}"] ？謝謝！

Answer 1

您的 API 定義是正確的。 它甚至應該在沒有encoding的情況下工作，因為對象和對象數組的Content-Type默認情況下是application/json 。

問題是 Swagger UI 和 Swagger Editor 還沒有正確支持多部分主體中的 JSON。 以下是您可以跟蹤的相關問題：

• 請求中不遵守編碼屬性
• 對於具有 JSON 部分的 mime/multipart 上傳，生成的 CURL 似乎是錯誤的 - 缺少 'type=' 選項，錯誤的引號
• multipart/form-data 應該支持自定義內容類型選擇