Allowing a response to contain both a file and other data in an object

[LindsayOSunrise]

My current attempt:

get:
      summary: Get Practice Information
      description: |
        This call will return information about a specific Practice.
      tags:
      - Practice
      parameters:
      - name: apikey
        in: query
        description: apikey
        required: true
        type: string
      - name: PracticeName
        in: query
        description: Name of Practice
        required: true
        type: string
      produces:
        - multipart/form-data
      responses:
        200:
          description: Information about a Practice
          schema:
            $ref: '#/definitions/PracticeInfo'
        400:
          description: Application error
          schema:
            $ref: '#/definitions/ApplicationError'
        500:
          description: System error
          schema:
            $ref: '#/definitions/SystemError'

I'd like to return a .png file along with the other information in definitions/PracticeInfo (which is just an object with a bunch of string properties.
I tried adding

Logo:
        type: file
        description: logo of Practice

to the definitions/PracticeInfo object, but the Swagger ui says this is not a valid definition. I can't seem to find exactly where in the Swagger spec it says that files cannot be in objects, but it seems they cannot be. I can also put just the .png file in the response and that works fine, but I can't get both together. I know that application/form-data will allow me to put this kind of data in as a parameter, but that's for requests, not responses.

Is this a bug? Intended behavior? A future task? Am I just missing the obvious way to do this?

[ePaul]

Note that OpenAPI is not a RPC framework (where it might be possible to put a file into an object, and then return this from a method), but a description language for what goes "over the wire".

An OpenAPI schema describes (apart from the type: file special case) a JSON value (object, array or primitive), being serialized into JSON format (or XML, but I'll ignore that for simplicity).

For the type: file, which is only allowed directly in a response or body parameter schema, it instead means "this thing is not JSON, but something else which won't be specified nearer here".

You can't put a "something else" into JSON without first converting it into some JSON structure – and if you are doing this, you can simply describe the conversion result (e.g. a base64-encoded string .

I guess one could use a multipart-message and have one part being the PNG file, and other parts being the other properties, but OpenAPI 2.0 doesn't provide any mechanism for that.

(I hope we get something for this in OpenAPI 3, which is being worked on now.)

[fehguy]

See #878 which describes the general mechanism for describing the schema of files in either input or outputs