Question

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

@Entity
@Table(name = "Teen")
public class Teen implements Serializable {

    @Id
    private String email;

    @OneToOne(cascade = CascadeType.ALL, fetch = FetchType.LAZY, orphanRemoval = true, mappedBy = "teen")
    private User user;
}

Swagger编辑器抛出以下验证错误：

Swagger错误：数据与来自＆＃39; oneOf＆＃39;
的任何架构都不匹配

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

Answer 1

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

Answer 2

这在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规范的相关部分：
Considerations for File Uploads
Special Considerations for multipart Content

Answer 3

使用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

在Swagger中，如何定义一个使用文件和模式参数的API？

3 个答案: