6

我正在尝试使用 Swagger 定义一个接受实际文件和描述文件内容的模式对象的 API。这是 Swagger YAML 的一个片段。但是，它不会在 Swagger 编辑器中验证。 

/document:
  post:
    summary: Api Summary
    description: Api Description
    consumes:
      - multipart/form-data
    parameters:
      - name: documentDetails
        in: formData
        description: Document Details
        required: true
        schema:
          $ref: '#/definitions/Document'
      - name: document
        in: formData
        description: The actual document
        required: true
        type: file

Swagger 编辑器引发以下验证错误：

Swagger 错误：数据与“oneOf”中的任何模式都不匹配

我错过了什么吗？或者这不是 Swagger 支持的功能吗？

4

3 回答 3

3

这在 OpenAPI 3.0 中是可能的，但在 OpenAPI/Swagger 2.0 中是不可能的。

OpenAPI/Swagger 2.0 不支持表单数据中的对象。表单参数可以是原始值、原始数组和文件，但不能是对象。因此，您的示例无法使用 OpenAPI 2.0 来描述。

在 OpenAPI 3.0 中，您可以使用：

paths:
  /document:
    post:
      summary: Api Summary
      description: Api Description
      requestBody:
        required: true
        content:
          multipart/form-data:

            # Form parameters from 2.0 become body schema properties in 3.0
            schema:
              type: object
              properties:

                # Schema properties correspond to individual parts
                # of the multipart request
                document:
                  # In 3.0, files are binary strings
                  type: string
                  format: binary
                  description: The actual document

                documentDetails:
                  $ref: '#/components/schemas/Document'
                  # The default Content-Type for objects is `application/json`
              required:
                - document
                - documentDetails

3.0 规范的相关部分：
文件上传
的注意事项 多部分内容的特殊注意事项

于 2017-06-22T09:59:45.750 回答
2

swagger 不支持 formData 中的 type 'object'，仅作为 body 参数。

于 2015-11-19T22:51:55.270 回答
0

使用 Swagger 2.0 是不可能的，您只能将其读取为类型 'file' ，

https://swagger.io/docs/specification/2-0/file-upload/

在相关说明中，请注意 Swagger 2.0 也不支持上传文件数组，但 Open API 3.0 支持。

https://github.com/OAI/OpenAPI-Specification/issues/254

于 2018-09-10T11:02:57.273 回答