在 Swagger 中，如何定义一个使用文件和模式参数的 API? [英] In Swagger, how to define an API that consumes a file along with a schema parameter?

问题描述

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

I am trying to use Swagger to define an API that accepts an actual file and a schema object that describes the contents of a file. Here is a snippet of the Swagger YAML. However it won't validate in the Swagger Editor.

/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 编辑器抛出以下验证错误:

The Swagger Editor throws the following validation error:

Swagger 错误:数据与oneOf"中的任何架构都不匹配

Swagger Error: Data does not match any schemas from 'oneOf'

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

Am I missing something? Or Is this not a supported feature of Swagger?

推荐答案

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

This is possible in OpenAPI 3.0, but not in OpenAPI/Swagger 2.0.

OpenAPI/Swagger 2.0 不支持表单数据中的对象.表单参数可以是原始值、原始数组和文件，但不能是对象.所以你的例子不能用 OpenAPI 2.0 来描述.

OpenAPI/Swagger 2.0 does not support objects in form data. Form parameters can be primitive values, arrays of primitives, and files, but not objects. So your example cannot be described using OpenAPI 2.0.

在 OpenAPI 3.0 中，您可以使用:

In OpenAPI 3.0, you can use:

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 规范的相关部分:
文件上传注意事项
特别注意事项对于多部分内容

Relevant parts of the 3.0 Specification:
Considerations for File Uploads
Special Considerations for multipart Content

这篇关于在 Swagger 中，如何定义一个使用文件和模式参数的 API?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！