OpenAPI 3.0 - how to define file download operation correctly

Question

I use online Swagger Editor with OpenAPI 3.0 and I have to create a definition file download. I develop server-side and a customer should be able to create a client using YAML description without my "addition explanation". The relevant part of YAML is:

/files/download/{fileName}:
get:
  summary: download file
  operationId: downloadFile
  description: this API is for file download
  parameters:
    - in: path
      name: fileName
      schema:
        type: string
      required: true
      description: The name of file to download
  responses:
    200:
      description: Operation performed successfully.
      content:
        application/octet-stream:
          schema:
            type: string
            format: binary
   ...

The questions are:

Content. Currently, it is defined as octet-stream as a most common type, but actually, it depends on the type of a file from some predefined set of file types. Is there any way to define such kind of mapping (file type/content type) and use it with a content tag?
The response header should include a key/value pair attachment or inline and file name. The file name is defined in path - {fileName}. Is there any way to describe the concatenation of enum {attachment, inline} and the value of fileName?

Just to be clear, you don't want to use objects to define your content schema? So for example (object containing `fileType` as `string` and `contentType` as `string` ) this will be defined in the `components schema` section of your `yaml`. (you could do the same with enums by defining it in your component schema then using `$ref` to point to your `enum`) — VVS, Aug 24 '21 at 12:49

score 1 · Answer 1 · edited Dec 02 '22 at 19:47

I believe content is what you're looking for. You can also use contentReference to reference a reusable object in components. For example:

paths:
  /files/{fileName}:
    get:
      summary: download file
      operationId: downloadFile
      description: this API is for file download
      parameters:
        - in: path
          name: fileName
          schema:
            type: string
          required: true
          description: The name of file to download
      responses:
        200:
          description: Operation performed successfully.
          content:
            application/pdf:
              schema:
                type: string
                format: binary

components:
  contentTypes:
    application/pdf:
      schema:
        type: string
        format: binary

OpenAPI 3.0 - how to define file download operation correctly

1 Answers1