only 1 response message per http response code is shown

[conorroche]

In our API we can many multiple response messages that can have the same numeric http code

for example

{
"code" : 403,
"message" : "access_denied|If the caller is neither the rider nor the driver"
}, {
"code" : 403,
"message" : "blocked|If the recipient has blocked the sender from contacting him/her"
}

In previous versions of swagger ui this worked fine but since 2.1 it seems to only show 1 per http code.

The json can be seen here:
https://api.car.ma/apidoc/ref/bookings.json

[webron]

@conorroche - unfortunately, that's not a valid Swagger definition. It wasn't valid in Swagger 1.2 and it's not valid in 2.0. There's a thread somewhere explaining why it is not valid (or relevant), I can try finding it if you'd like.

[conorroche]

@webron if you could find that it would be good, im guessing its down to interpretation as ive reread the 1.2 spec scetion related to response messages and i dont see where it describes that having multiple messages with the same http code is not valid, I do note that in v2 of the spec the response object is keyed on the numeric code which does mean only 1 per code is possible. shame as this was something that has worked for over 2 years. Seems like a spec bug to me as why shouldnt you be able to use say a 404 to represent different items not being found or a 400 to represent different input field errors.

[conorroche]

@webron here is a spec bug related to this: OAI/OpenAPI-Specification#398

[webron]

I'm a bit sensitive when it comes to wording - it's not a spec bug, it's a feature request. It's not a bug if it works as intended.

As for the elaborate explanation, you can find it in the following thread - https://groups.google.com/d/topic/swagger-swaggersocket/KAmdyf4aRGs/discussion.

I'm afraid I'm going to close this one as by-design.

[conorroche]

@webron fair enough, I'm not sure that your interpretation of the 1.2 spec is definitively correct but regardless I am still left with something that worked in version swagger-ui-2.1.8-M1 and earlier of swagger ui no longer working in version so 2.1.0. It will take me a while to change my project to group different responses of the same code together in the meantime I will do a simple patch on the swagger ui to support multiple messages with the same code. thanks for looking into it.

[webron]

@conorroche - if it reassures you, I wrote the 1.2 spec document ;) I agree that the spec doesn't say so explicitly, but it was the intent and probably was just missed. Created the 1.2 spec document was a lot of reverse engineering process, unlike the 2.0 spec.

Since the current version of the ui converts older versions of Swagger definitions to 2.0 before processing them for display, it's just not possible to support it right now. If you can't change your definition, you'd probably better off reverting to an older version of the UI.

[conorroche]

@webron i didnt realise you wrote it ;) so i think you win that one! I appreciate your feedback

[webron]

I've been wrong before, even in the spec, so no worries. It's just an issue we've discussed a few times and I hope the linked thread explains the reasoning of it.