OpenAPI 示例多部分表单数据

Question

我在 API 端点中有一个 multipart/form-data POST，它需要一些键/值字符串，并通过 key 上传文件files。

我相信我已经在 OpenAPI 中正确定义了它；

"requestBody": {
  "required": true,
  "content": {
    "multipart/form-data": {
      "schema": {
        "properties": {
          "file": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "binary"
            }
          },
          "myKey1": {
            "type": "string"
          },
          "myKey2": {
            "type": "string"
          }
        }
      },
      "examples": {
        "value": ?
      }
    }
  }
},

但是，我不确定如何描述该领域的多部分/表单数据的示例examples。

我认为我不需要表示文件（尽管这将是一个额外的好处），而只需表示myKey1键myKey2和值。

Answer 1

你的美洲国家组织的定义似乎是正确的。您可以定义如下所示的示例：

      "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "properties": {
                  "file": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "binary"
                    },
                    "example": [
                      {
                        "externalValue": "http://www.africau.edu/images/default/sample.pdf"
                      }
                    ]
                  },
                  "myKey1": {
                    "type": "string",
                    "example": "myKey1Example"
                  },
                  "myKey2": {
                    "type": "string",
                    "example": "myKey2Example"
                  }
                }
              }
            }
          }
        },

externalValue可以添加指向 Open API 规范中的示例文件 URL。这仅用于文档目的。

但是，它不会显示在 swagger-ui 中，因为 swagger-ui 还不支持它。它在[1]中被跟踪。

[1] https://github.com/swagger-api/swagger-ui/issues/5433