OpenAPI 示例多部分表单数据答案

【问题标题】：OpenAPI Example multipart form dataOpenAPI 示例多部分表单数据
【发布时间】：2021-08-24 20:56:49
【问题描述】：

我在 API 端点中有一个 multipart/form-data POST，它接受一些键/值字符串，并通过键 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 键和值。

【问题讨论】：

标签： schema multipartform-data openapi

【解决方案1】：

您的 OAS 定义似乎是正确的。您可以定义如下所示的示例：

      "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 可以添加指向开放 API 规范中的示例文件 URL。这仅用于文档目的。

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

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

【讨论】：

好的，谢谢，我了解example 的用例，但您能提供examples 数组的用例吗？
仅用于表示API使用者可以向该资源上传多个文件
你确定吗？从规范的阅读方式来看，examples 似乎是一个不同示例的数组
externalValue 仅在媒体类型 examples（复数 exampleS）中受支持，在架构/属性 example 中不受支持。
@myol，对不起，我的印象是你在问这个问题中的示例数组。是的，examples 用于为参数提供多个示例。您可以获取更多信息here。