swagger - 打开 api 3 发布一组文件

Question

我正在使用 swagger hub 到 create this API ;但它不支持 UI 中的多个文件，所以我不确定我这样做是否正确

我的目标是拥有以下内容

item:{Json describe the item}
images[] = images for item posted as an array
titles[] = Parallel array to images that has the title for image
alt_texts[] = Parallel array to images that has the alt text for image

这必须是多部分的，因为它是文件；但不确定我是否正确设置了结构。

Swagger/开放 API 代码

post:
  summary: Add a new item to the store
  description: ''
  operationId: addItem
  requestBody:
    content:
      multipart/form-data:
        schema:
          $ref: '#/components/schemas/NewItemWithImage'
    description: Item object that needs to be added to the store
    required: true


NewItemWithImage:
  type: object
  properties:
    item:
      $ref: '#/components/schemas/NewItem'
    images[]:
      type: array
      items:
        type: string
        format: binary
    titles[]:
      type: array
      items:
        type: string
    alt_texts[]:
      type: array
      items:
        type: string
    variation_ids[]:
      type: array
      items:
        type: string
  required:
    - item

Answer 1

根据 File Upload OpenAPI 3 规范中的部分:

文件上传

Files use a type: string schema with format: binary or format: base64, depending on how the file contents will be encoded.

多文件上传

Use the multipart media type to define uploading an arbitrary number of files (an array of files):

      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                filename:
                  type: array
                  items:
                    type: string
                    format: binary

您当前的定义完全符合规范:

requestBody:
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/NewItemWithImageUrl'
    multipart/form-data:
      schema:
        $ref: '#/components/schemas/NewItemWithImage'

NewItemWithImage:
  type: object
  properties:
    item:
      $ref: '#/components/schemas/NewItem'
    images[]:
      type: array
      items:
        type: string
        format: binary
    titles[]:
      type: array
      items:
        type: string
    ...