Springdoc、OpenApi如何编写multipart/form-data、文件上传接口

原创

已于 2022-07-13 17:00:07 修改 · 6.1k 阅读

3 ·

CC 4.0 BY-SA版权

文章标签：

#java #spring boot

于 2022-07-13 16:52:00 首次发布

本文介绍了如何在SpringBoot中使用Springdoc和OpenApi规范来创建支持multipart/form-data的文件上传接口，包括设置请求体内容类型、定义schema及实际代码示例。详细解读了官方文档中的规则，并给出了一个Swagger UI中的展示和操作实例。

Springdoc、OpenApi如何编写multipart/form-data、文件上传接口

先上swagger官方文档:

https://swagger.io/specification/#schema

目前我使用的springdoc版本为1.69
参考内容:

Special Considerations for multipart Content

It is common to use multipart/form-data as a Content-Type when transferring request bodies to operations. In contrast to 2.0, a schema is REQUIRED to define the input parameters to the operation when using multipart content. This supports complex structures as well as supporting mechanisms for multiple file uploads.

When passing in multipart types, boundaries MAY be used to separate sections of the content being transferred — thus, the following default Content-Types are defined for multipart:

If the property is a primitive, or an array of primitive values, the default Content-Type is text/plain

If the property is complex, or an array of complex values, the default Content-Type is application/json

If the property is a type: string with format: binary or format: base64 (aka a file object), the default Content-Type is application/octet-stream

翻译过来就是：

multipart内容的特殊注意事项

在将请求体传输到操作时，通常使用 multipart/form-data 作为 Content-Type。与2.0不同，在使用多部分内容时，模式是 REQUIRED，用于定义操作的输入参数。这支持复杂的结构以及支持多文件上传的机制。

当传递多部分类型时，边界可用于分隔正在传递的内容的各个部分ーー因此，为多部分定义了以下默认内容类型:

如果属性是基元或基元值数组，则默认 Content-Type 为 text/plain

如果属性是复杂的，或者是复杂值的数组，默认的 Content-Type 是 application/json

如果属性是 type: string，格式为: binary 或 format: base64(又名 file 对象) ，则默认的 Content-Type 是 application/octet-stream

范例Examples:

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          id:
            type: string
            format