Don't override references when using a ResponseSchema for different cases

[gabisurita]

The current implementation overrides the references when using a same schema for different responses cases. e.g:

class ErrorSchema(colander.MappingSchema):

    code = colander.SchemaNode(colander.Integer())
    message = colander.SchemaNode(colander.String())

response_schemas = {
    '400': ErrorResponseSchema(
        description="The request is invalid."),
    '401': ErrorResponseSchema(
        description="The request is missing authentication headers."),
}

Both will be at #/responses/ErrorResponseSchema

[gabisurita]

One approach would be to require a unique name for the response. Thoughts?

[glasserc]

Well, definitely throwing an exception if we get to this case is better than silently overriding it... but not much better. One thing we could do is generate unique names, calling one #/responses/ErrorResponseSchema1 and the other #/responses/ErrorResponseSchema2, but this seems like it could be pretty brittle unless we come up with an unambiguous/canonical name for the responses. (Do clients use the reference paths for anything?) Maybe we could detect this case and just not make references in this case, but just let the responses live underneath each operation?