Cannot have multiple ApiResponse attributes with same status code (breaks openapi)

#1

I just recently discovered that having multiple ApiResponse attributes with the same status code but different descriptions breaks openapi endpoint.

The exception thrown was cryptic and took a bit to figure it out. The service calls don’t seem to break, but any usage of the openapi definition endpoint will.

I’m not sure if this is a limitation of the openapi schema or not. But, what I want to be able to do in my case is have for example, multiple attributes with different descriptions as there are multiple ways to throw status codes.

[ApiResponse(HttpStatusCode.Unauthorized, "This order doesn't belong to calling user.")]
[ApiResponse(HttpStatusCode.Unauthorized, "Invalid user.")]

If it’s a limitation of schema, i’ll just pass string.empty i guess

#2

Which version of ServiceStack are you using? In v4.5.13 which is available on MyGet you should not get any exceptions when annotate DTO with [ApiResponse] with the same Http status code.

Open API specification does not allow to specify several descriptions/return types for the same status code in response, you should combine all status code descriptions into one or use different status codes for different descriptions.

[ApiResponse(HttpStatusCode.Unauthorized,
@"Return values: 
This order doesn't belong to calling user.
Invalid User.
")]

In v4.5.13 if you annotate DTO with multiple [ApiResponse] with the same status code only the latest attribute is used.

#3

I would also add from an API Design perspective you should not be overloading the same status code with multiple error conditions i.e. your clients should only need to look at the Response Status Code to know how to properly handle the request.

Note: The Unauthorized HTTP Header should only be used when accessing a protected resource from an Unauthenticated User. The clients handling of this error condition would be something like redirecting to the login screen to authenticate the user. If the User is Authenticated but they don’t have access to the protected resource return a 403 Forbidden HTTP Error instead, which indicates the User is Authenticated but they don’t have permission to access the selected resource. In which case Re-authenticating an already authenticated user will not solve their problem, they’ll need to instead request access to the resource they’re trying to access.