You're getting the error in the model, because that's not the way to define required properties.
The correct form would be:
"my_response_object": {
"type": "object",
"required": [ "result" ],
"properties": {
"result": {
"type": "string",
"description": "value of 'success' or 'error', indicated whether was successful"
},
"message": {
"type": "string",
"description": "an error message if there was an issue"
},
"filename": {
"type": "string",
"description": "the filename to return if the request was successful"
}
}
}
Anything not in the required
property is assumed to be optional. Keep in mind that this implies that it's possible to get both message
and filename
.
You can then use this model for your 200 response.
However - when it comes to REST API design, this breaks one of the more common standards. The status codes, taken from the HTTP protocol are meant to convey the outcome of the operation. 2XX are used for successful responses, 4XX are for errors due to bad user input, 5XX are for problems on the server side (3XX are for redirects). What you're doing here, is tell the client - the operation was successful, but in fact, it can be an error.
If you can still modify the API, I'd highly recommend making that distinction using the status codes, even using the fine tuned distinctions such as 200 for a successful GET operation, 201 for successful POST (or creation) operation and so on, based on the definitions here - http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html.
Best Answer
OpenAPI 2.0
OAS2 does not support multiple response schemas per status code. You can only have a single schema, for example, a free-form object (
type: object
withoutproperties
).OpenAPI 3.0
In OAS3 you can use
oneOf
to define multiple possible request bodies or response bodies for the same operation:However, it's not possible to map specific response schemas to specific parameter values. You'll need to document these specifics verbally in the
description
of the response, operation and/or parameter.Here's a possibly related enhancement request:
Allow operationObject overloading with get-^ post-^ etc
Note for Swagger UI users: As of this writing (December 2018) Swagger UI does not automatically generate examples for
oneOf
andanyOf
schemas. You can follow this issue for updates.As a workaround, you can specify a response
example
orexamples
manually. Note that using multipleexamples
require Swagger UI 3.23.0+ or Swagger Editor 3.6.31+.