How to define an OpenAPI description to upload an image?

Question

I am writing an OpenAPI description to upload images and retrieve images.

I am not sure which format and type I should use.

This is what I've tried:

/uploadimage:
    post:
      tags: 
        - images
      summary: to upload image
      requestBody:  
        content:
          application/json:
            schema:
              type: object
              properties:
                imageID:
                  type: integer
                  example: 103983
                image:
                    type: string
                    format: byte
                          

Answer 1

There are two ways you can do this.

First and simplest, you can upload files directly using the relevant media type. For example,

requestBody:  
  content:
    image/png: # means: content is an image in a byte array.
      schema:
        type: string
        format: binary

The reason this is simple is that it is very easy for the client to make this call:

POST /my-path HTTP/1.1
Content-Type: image/png
[image file byte array here]

If you want to send other metadata alongside the request, as it appears you want to do in your question example, you should use a mutlipart form request. For example,

requestBody:  
  content:
    multipart/form-data: # means: content consists of multiple parts with a separator.
      schema:
        type: object
        properties:
          imageID: # the metadata you want to send with the image
            type: integer
            example: 103983
          image: # the actual image file
            type: string 
            format: binary

The problem with multipart requests is that it is complex for your clients to make calls. To call the above endpoint looks like this:

POST /my-path HTTP/1.1
Content-Type: multipart/form-data; boundary=xxx 
--xxx
Content-Disposition: form-data; name="imageID"
103983 
--xxx
Content-Disposition: form-data; name="filename"; filename="imageid103983.png"
Content-Type: image/png
[image file byte array here]
--xxx--

So, even though you can pass metadata with your file, it is much simpler and easier to pass just the file.