Regression: Inherited response data not displaying in Swagger-UI when using swagger-js v2.1.10

[xiehan]

Here's v2.1.9:

And here's v2.1.10:

Here's the relevant parts of our spec, other stuff not relevant to this bug removed for length:

{
    "swagger": "2.0",
    "paths": {
        "/identity/v2/user": {
            "get": {
                // ...
                "responses": {
                    "200": {
                        "description": "Successfully found the user",
                        "schema": {
                            "$ref": "#/definitions/UserDocument"
                        },
                        "$ref": "#/responses/200"
                    },
                    "401": {
                        "$ref": "#/responses/401WithDocument"
                    },
                    "429": {
                        "$ref": "#/responses/429WithDocument"
                    },
                    "500": {
                        "$ref": "#/responses/500WithDocument"
                    },
                    "503": {
                        "$ref": "#/responses/503WithDocument"
                    }
                }
            }
        },
    },
    "responses": {
        "429": {
            "description": "The client has exceeded the number of daily calls as per their rate limit. For now, this only applies to prototype applications and untrusted clients. Trusted clients will never be rate-limited, nor will any production apps.",
            "headers": {
                "X-RateLimit-Limit": {
                    "description": "The number of allowed requests in the current period",
                    "type": "integer"
                },
                "X-RateLimit-Remaining": {
                    "description": "The number of remaining requests in the current period",
                    "type": "integer"
                },
                "X-RateLimit-Reset": {
                    "description": "The number of seconds left in the current period",
                    "type": "integer"
                }
            }
        },
        "429WithDocument": {
            "schema": {
                "$ref": "#/definitions/ErrorDocument"
            },
            "$ref": "#/responses/429"
        },
        "200": {
            "description": "The request completed successfully",
            "headers": {
                "X-RateLimit-Limit": {
                    "description": "The number of allowed requests in the current period",
                    "type": "integer"
                },
                "X-RateLimit-Remaining": {
                    "description": "The number of remaining requests in the current period",
                    "type": "integer"
                },
                "X-RateLimit-Reset": {
                    "description": "The number of seconds left in the current period",
                    "type": "integer"
                }
            }
        },
        "401": {
            "description": "The client is not authorized to complete this request. Check to ensure a valid access token was passed in the headers."
        },
        "500": {
            "description": "A server error",
            "headers": {
                "X-RateLimit-Limit": {
                    "description": "The number of allowed requests in the current period",
                    "type": "integer"
                },
                "X-RateLimit-Remaining": {
                    "description": "The number of remaining requests in the current period",
                    "type": "integer"
                },
                "X-RateLimit-Reset": {
                    "description": "The number of seconds left in the current period",
                    "type": "integer"
                }
            }
        },
        "503": {
            "description": "The system is undergoing maintenance and we are unable to fulfill this request. Look for Retry-After in the header to see the predicted time the system will be back up.",
            "headers": {
                "Retry-After": {
                    "description": "The predicted time the system will be back up",
                    "type": "string",
                    "format": "date-time"
                }
            }
        },
        "401WithDocument": {
            "schema": {
                "$ref": "#/definitions/ErrorDocument"
            },
            "$ref": "#/responses/401"
        },
        "500WithDocument": {
            "schema": {
                "$ref": "#/definitions/ErrorDocument"
            },
            "$ref": "#/responses/500"
        },
        "503WithDocument": {
            "schema": {
                "$ref": "#/definitions/ErrorDocument"
            },
            "$ref": "#/responses/503"
        }
    }
}

[webron]

@xiehan - I'm afraid none of the "XXXWithDocument" definitions is valid. I'm even surprised it worked in previous versions, but this is not really a bug. Not only that a Response Object can't take a $ref at its root (spec restricition), even if it had, you couldn't use it alongside a schema definition at the same level (that's a restriction of JSON Reference, not of the spec).

[xiehan]

a Response Object can't take a $ref at its root (spec restricition)

I don't understand this. Then how are the top-level Response Definitions intended to be used?

you couldn't use it alongside a schema definition at the same level (that's a restriction of JSON Reference, not of the spec)

So is there any way to create any sort of inheritance model among Responses at all? If not, I find that incredibly frustrating. The amount of copy-pasting I've had to do for Swagger v2 compared to v1.2 has increased enormously, to the point where it's becoming unmanageable.

[webron]

There's a difference between the top-level Response Definitions Object than the operation-level responses.

The top-level Response Definitions Object is a map between a name and a Response Object.

However, the Response Object is a map between an HTTP response code (or default) and either a Response Object or a reference - and that's how the top-level Response Definitions are intended to be referenced.

The inheritance that can be defined in the responses is only at the schema level. 1.2 didn't even allow you to have top level definitions and you had to repeat everything anyways. I do understand the frustration though, it's just something we didn't think of when creating the spec. To improve that, I'd ask you to open an issue on the spec so we can take into account in the next version. I admit it makes sense to add such level of extensible.

[xiehan]

All right, ticket open. And just FYI, part of the problem for me was that swagger-php used to have a feature called 'Partials' in 1.x, which was designed to solve exactly this problem -- allowing annotations to be reused so you didn't have to copy-paste things over and over. Unfortunately, Partials were removed in 2.x because the maintainers said "Swagger 2.0 now has definitions! We don't need partials anymore!" But now it seems like there are some use cases for partials, like this one, that fell through the cracks.

[webron]

@xiehan - aha! Thanks for providing the details. Definitely helps explaining the expectations.