Repository navigation
Allowing a response to contain both a file and other data in an object #722
Description
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?
Activity
ePaul commentedon Jul 1, 2016
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: filespecial 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 commentedon Feb 1, 2017
See #878 which describes the general mechanism for describing the schema of files in either input or outputs