swagger 3/OAS3 提交文件数据以及常规数据多部分请求

Question

我有以下 swagger 代码 addCustomer 用于发送包含图像和其他 json 数据的请求。当我从 swagger hub 运行代码时；它只是发送 json。我定义这个正确吗？它不应该发送多部分请求吗？

post:
  tags:
    - customers
  summary: Add a new customer to the store
  description: ''
  operationId: addCustomer
  requestBody:
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/NewCustomerWithImageUrl'
      application/xml:
        schema:
          $ref: '#/components/schemas/NewCustomerWithImageUrl'
      multipart/form-data:
        schema:
          $ref: '#/components/schemas/NewCustomerWithImage'
    description: Customer object that needs to be added to the store
    required: true


NewCustomerWithImage:
  type: object
  allOf:
    - $ref: '#/components/schemas/NewCustomer'
  properties:
    Image:
      type: string
      format: binary

Person:
  type: object
  required:
    - first_name
  properties:
    first_name:
      type: string
      example: John
    last_name:
      type: string
      example: Doe
    email:
      type: string
      example: john@example.com
    phone_number:
      type: string
      example: 555-555-5555
    address_1:
      type: string
      example: 123 Nowhere Street
    address_2:
      type: string
      example: Apartment 123
    city:
      type: string
      example: Rochester
    state:
      type: string
      example: New York
    zip:
      type: string
      example: '14445'
    country:
      type: string
      example: United States
    comments:
      type: string
      example: A great customer
    custom_fields:
      type: object
      minProperties: 0
      maxProperties: 10
      additionalProperties:
        type: string
      example:
        secondary phone number: '555-555-5555'
NewCustomer:
  type: object
  allOf:
    - $ref: '#/components/schemas/Person'
  properties:
    company_name:
      type: string
      example: PHP Point Of Sale
    tier_id:
      type: integer
      format: uuid
      example: 0
    account_number:
      type: string
      example: '3333'
    taxable:
      type: boolean
      example: false
    tax_certificate:
      type: string
      example: '1234'
    override_default_tax:
      type: boolean
      example: false
    tax_class_id:
      type: integer
      format: uuid
      example: 0
    balance: 
      type: number
      format: float
      example: 22.99
    credit_limit:
      example: null
    points:
      type: integer
      format: int32
      example: 333
    disable_loyalty:
      type: boolean 
      example: true
    amount_to_spend_for_next_point:
      type: number
      format: float
      readOnly: true
      example: 10.00
    remaining_sales_before_discount:
      type: integer
      format: int32
      readOnly: true
      example: 0
  xml:  
    name: Customer

Json 发送:

{"first_name":"John","last_name":"Doe","email":"john@example.com","phone_number":"555-555-5555","address_1":"123 Nowhere Street","address_2":"Apartment 123","city":"Rochester","state":"New York","zip":"14445","country":"United States","comments":"A great customer","custom_fields":{"secondary phone number":"555-555-5555"},"company_name":"PHP Point Of Sale","tier_id":0,"account_number":"3333","taxable":false,"tax_certificate":"1234","override_default_tax":false,"tax_class_id":0,"balance":22.99,"credit_limit":null,"points":333,"disable_loyalty":true,"Image":"string"}

Swagger 中心文件:

https://app.swaggerhub.com/apis/PHP-Point-Of-Sale/PHP-Point-Of-Sale/1.0#/customers/addCustomer

Answer 1

1) Swagger UI(SwaggerHub 使用)尚不支持 OpenAPI 3.0 定义的表单数据和文件上传。请关注此问题以获取状态更新:https://github.com/swagger-api/swagger-ui/issues/3641 UPD:Swagger UI 现在支持 OAS3 的文件上传。

2) 如果“包含图像和其他 JSON 数据的请求”意味着像这样的 multipart 请求 –

POST /foo HTTP/1.1
Content-Type: multipart/form-data; boundary=ABCDEF123

--ABCDEF123
Content-Disposition: form-data; name="Customer"
Content-Type: application/json

{
  "foo": "bar"
}

--ABCDEF123
Content-Disposition: form-data; name="Image"; filename="image1.png"
Content-Type: application/octet-steam

{…image content…}

--ABCDEF123--

那么请求体定义应该是这样的:

      requestBody:
        content:
          ...
          multipart/form-data:
            schema:
              type: object
              properties:
                Customer:   # <--- name of the part in a multipart request
                  $ref: '#/components/schemas/NewCustomer'
                Image:      # <--- name of the part in a multipart request
                  type: string
                  format: binary
              required:
                - Customer
                - Image

更多信息:

• How to describe a multipart response using OpenAPI (Swagger)?就在这里
• Special Considerations for multipart Content在 OpenAPI 3.0 规范中
• Multipart Requests在 swagger.io 上