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

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: [email protected]
    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

杰森发来的话：

{"first_name":"John","last_name":"Doe","email":"[email protected]","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 Hub文件：

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

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)?在这里
• 在OpenAPI 3.0规范中的Special Considerations for multipart Content
• Multipart Requests on swagger.io

3）你对allOf的使用看起来不正确：

NewCustomer:
  type: object
  allOf:
    - $ref: '#/components/schemas/Person'
  properties:
    company_name:
      type: string
      example: PHP Point Of Sale

所有合并的子文件应该在allOf内：

NewCustomer:
  type: object
  allOf:
    - $ref: '#/components/schemas/Person'
    - type: object
      properties:
        company_name:
          type: string
          example: PHP Point Of Sale