OpenAPI 3 / 3.1 handling of binary content

[PaulStryck]

Description

OpenAPI 3 has dropped the file type. It looks like this is not reflected here.

When using type: file in a schema:

"content": {
  "application/zip":  {
    "schema": {
      "type": "file"
    }
  }
}

the corresponding typescript type is created as (Blob | File). Which is the expected behaviour for OpenApi v2 but the above is not a valid OpenAPI 3 / 3.1 spec as the type: file is not supported anymore.

In OpenAPI 3:

Content transferred in binary (octet-stream) MAY omit schema

"content": {
  "application/zip":  {}
}

Or use type: string with contentEncoding keyword.

"content": {
  "application/zip":  {
    "schema": {
      "type": "string",
      "contentEncoding": "base64"
    }
  }
}

However, this will generate typescript types of either unknown or string.

OpenAPI specification (optional)

{
  "openapi": "3.1.0",
  "paths": {
    "/foo": {
      "get": {
        "responses": {
          200: {
            "content": {
              "image/png":  {
                "schema": {
                  "type": "string",
                  "contentMediaType": "image/png",
                  "contentEncoding": "base64"
                }
              }
            }
          }
        }
      }
    }
    "/bar": {
      "get": {
        "responses": {
          200: {
            "content": {
              "application/zip":  {}
            }
          }
        }
      }
    }
  }
}

Configuration

No response

System information (optional)

No response

[mrlubos]

Thanks for reporting @PaulStryck, will check

[mrlubos]

Hey @PaulStryck, mind adding what's the expected result here?

[PaulStryck]

Thanks for looking into it.

I would expect to get (Blob | File) type annotations when using OpenAPI v3 specs.

Currently these type annotations are produced:

export type GetFooResponse = (Blob | File);
export type GetBarResponse = (Blob | File);

when using the following OpenAPI spec:

{
  "openapi": "3.1.0",
  "info": {
    "version": "1.0.0",
    "title": "Test",
    "license": {
      "name": "Apache 2.0",
      "identifier": "Apache-2.0"
    }
  },
  "servers": [
    {
      "url": "http://localhost/"
    }
  ],
  "paths": {
    "/foo": {
      "get": {
        "responses": {
          200: {
            "description": "get foo",
            "content": {
              "image/png":  {
                "schema": {
                  "type": "file"
                }
              }
            }
          }
        }
      }
    },
    "/bar": {
      "get": {
        "responses": {
          200: {
            "description": "get bar",
            "content": {
              "application/zip":  {
                "schema": {
                  "type": "file"
                }
              }
            }
          }
        }
      }
    }
  }
}

"type": "file" is only allowed in OpenAPI v2.
The correct OpenAPI v3 spec produces:

export type GetFooResponse = string;
export type GetBarResponse = unknown;

with the following OpenAPI spec:

{
  "openapi": "3.1.0",
  "info": {
    "version": "1.0.0",
    "title": "Test",
    "license": {
      "name": "Apache 2.0",
      "identifier": "Apache-2.0"
    }
  },
  "servers": [
    {
      "url": "http://localhost"
    }
  ],
  "paths": {
    "/foo": {
      "get": {
        "responses": {
          200: {
            "description": "get foo",
            "content": {
              "image/png":  {
                "schema": {
-                 "type": "file
+                 "type": "string",
+                 "contentMediaType": "image/png",
+                 "contentEncoding": "base64"
                }
              }
            }
          }
        }
      }
    },
    "/bar": {
      "get": {
        "responses": {
          200: {
            "description": "get bar",
            "content": {
              "application/zip":  {
-               "schema": {
-                 "type": "file"
-               }
              }
            }
          }
        }
      }
    }
  }
}

Any response object with an omitted schema object for a "file like" mime type should generate a (Blob|File) type and set the Blob.type property accordingly, when parsing the response.
Any response with a populated schema object for a "file like" mime type should either generate a string type, or a (Blob|File) type and parse the base64 string to a Blob object directly in the request method. The latter is possibly a question of personal taste. I'd prefer parsing to Blob.