schema - OpenAPI 示例多部分表单数据

Question

我在 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 字段中描述 multipart/form-data 的示例。

我假设我不需要表示文件(尽管那会是一个额外的好处)，而只需要表示 myKey1 和 myKey2 键和值。

Answer 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 以指向 Open API Specification 中的示例文件 URL。这仅用于文档目的。

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

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