swagger 3/OAS 3 submit file data along with regular data mutlipart request

Question

I have the following swagger code addCustomer for sending a request that includes an image along with other json data. When I run code from swagger hub; it just sends json. Am I defining this right? Shouldn't it send multipart request?

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 sent:

{"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 Hub File:

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

Answer 1

1) Swagger UI (which SwaggerHub uses) does not yet support form data and file upload for OpenAPI 3.0 definitions. Follow this issue for status updates: https://github.com/swagger-api/swagger-ui/issues/3641 UPD: Swagger UI now supports file uploads for OAS3.

2) If "request that includes an image along with other JSON data" means a multipart request like this –

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

then the request body definition should look like this:

      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

More information:

• How to describe a multipart response using OpenAPI (Swagger)? here on SO
• Special Considerations for multipart Content in the OpenAPI 3.0 Specification
• Multipart Requests on swagger.io

Answer 2

File upload is supported in Open API v 3.0.3

Here's what my swagger.json looks like:

"/media/upload": {
      "post": {
        "tags": ["Media"],
        "name": "Upload Media",
        "description": "Uploads a Media file to the server.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "media": {
                    "type": "string",
                    "format": "base64"
                  }
                }
              }
            }
          }
        }
      }
    }

Here's how it show up in swagger: