OAS 3.1 file upload description is invalid

[yvoitenko]

According to OAS 3.1 specification, the format keyword is omitted for file uploads, and the contentEncoding and contentMediaType keywords are used instead.

In contrast with the 3.0 specification, the format keyword has no effect on the content-encoding of the schema. JSON Schema offers a contentEncoding keyword, which may be used to specify the Content-Encoding for the schema. The contentEncoding keyword supports all encodings defined in RFC4648, including "base64" and "base64url", as well as "quoted-printable" from RFC2045. The encoding specified by the contentEncoding keyword is independent of an encoding specified by the Content-Type header in the request or response or metadata of a multipart body -- when both are present, the encoding specified in the contentEncoding is applied first and then the encoding specified in the Content-Type header.

This affects the "Try request" functionality in different UI clients. For example, "Swagger UI" seems to have backwards compatibility, and allows file upload anyway, while "Stoplight Elements" doesn't.

So, currently it generates this from the file validation rule:

media:
  type: string
  format: binary
  description: 'A file intended for a document.'

But if we specify the OAS 3.1 dialect for generation, we should get something like this:

media:
  type: string
  contentMediaType: 'application/octet-stream'
  description: 'A file intended for a document.'

---

I created a workaround for this in my fork package, works well in both "Swagger UI" and "Stoplight Elements", for both OAS 3.0 and 3.1. Please, feel free to discover it in this PR.

Thanks!

[romalytvynenko]

@yvoitenko nice! Can you please submit a PR to this repo?

[yvoitenko]

@romalytvynenko no problem, here it is!

#569