add support for shared `responses` defs

[Kosta-Github]

• swagger supports the definition of shared responses objects which can be ref'ed by several endpoints
• see: https://github.com/reverb/swagger-spec/blob/4678d9fbe5723cb926b50fe0d1ae877c34e44a42/schemas/v2.0/schema.json#L81
• in order to deal with this potential additional level of indirection the swagger schema is normalized with respect to the responses defs before the existing algorithm is triggered

E.g. sample input schema:

{
    "swagger": "2.0",
    "info": {
        "version": "0.0.1",
        "title": "your title"
    },
    "paths": {
        "/persons": {
            "get": {
                "operationId": "get_person",
                "description": "Gets `Person` object.",
                "responses": {
                    "200": { "description": "empty schema" },
                    "201": {
                        "description": "inline schema",
                        "schema": { "type": "object", "properties": { "inline_schema": { "type": "string" } } }
                    },
                    "202": {
                        "description": "inline schema ref",
                        "schema": { "$ref": "#/definitions/direct_schema_ref" }
                    },
                    "203": { "$ref": "#/responses/empty_schema" },
                    "204": { "$ref": "#/responses/regular_schema" },
                    "205": { "$ref": "#/responses/indirect_schema" },
                    "206": { "$ref": "#/responses/same_name" },
                    "207": { "$ref": "#/responses/same_name_clash" }
                }
            }
        }
    },
    "responses": {
        "empty_schema": { "description": "empty schema" },
        "regular_schema": {
            "description": "regular schema",
            "schema": { "type": "object", "properties": { "regular_schema": { "type": "string" } } }
        },
        "indirect_schema": {
            "description": "indirect schema",
            "schema": { "$ref": "#/definitions/some_def" }
        },
        "same_name": {
            "description": "same name schema",
            "schema": { "$ref": "#/definitions/same_name" }
        },
        "same_name_clash": {
            "description": "same name clash schema",
            "schema": { "type": "object", "properties": { "same_name_clash_response": { "type": "string" } } }
        }
    },
    "definitions": {
        "direct_schema_ref": { "type": "object", "properties": { "direct_schema_ref": { "type": "string" } } },
        "some_def": { "type": "object", "properties": { "some_def": { "type": "string" } } },
        "same_name": { "type": "object", "properties": { "same_name": { "type": "string" } } },
        "same_name_clash": { "type": "object", "properties": { "same_name_clash_definition": { "type": "string" } } }
    }
}

gets normalized to:

{
  "swagger": "2.0",
  "info": {
    "version": "0.0.1",
    "title": "your title"
  },
  "paths": {
    "/persons": {
      "get": {
        "operationId": "get_person",
        "description": "Gets `Person` object.",
        "responses": {
          "200": { "description": "empty schema" },
          "201": {
            "description": "inline schema",
            "schema": { "$ref": "#/definitions/Response_get_person_201" }
          },
          "202": {
            "description": "inline schema ref",
            "schema": { "$ref": "#/definitions/direct_schema_ref" }
          },
          "203": { "description": "empty schema" },
          "204": {
            "description": "regular schema",
            "schema": { "$ref": "#/definitions/regular_schema" }
          },
          "205": {
            "description": "indirect schema",
            "schema": { "$ref": "#/definitions/some_def" }
          },
          "206": {
            "description": "same name schema",
            "schema": { "$ref": "#/definitions/same_name" }
          },
          "207": {
            "description": "same name clash schema",
            "schema": { "$ref": "#/definitions/Response_same_name_clash" }
          }
        }
      }
    }
  },
  "definitions": {
    "direct_schema_ref": {
      "type": "object",
      "properties": {
        "direct_schema_ref": { "type": "string" }
      }
    },
    "some_def": {
      "type": "object",
      "properties": {
        "some_def": { "type": "string" }
      }
    },
    "same_name": {
      "type": "object",
      "properties": {
        "same_name": { "type": "string" }
      }
    },
    "same_name_clash": {
      "type": "object",
      "properties": {
        "same_name_clash_definition": { "type": "string" }
      }
    },
    "regular_schema": {
      "type": "object",
      "properties": {
        "regular_schema": { "type": "string" }
      }
    },
    "Response_same_name_clash": {
      "type": "object",
      "properties": {
        "same_name_clash_response": { "type": "string" }
      }
    },
    "Response_get_person_201": {
      "type": "object",
      "properties": {
        "inline_schema": { "type": "string" }
      }
    }
  }
}

• inline response types will be removed and be replaced an explicit response type definition (either using an existing response type name) or generating it for the corresponding endpoint, method, and response code
• this will also improve the response type definitions from something like ResponseWithBody < 200, object > to a more meaningful declaration like: ResponseWithBody < 200, Response_findById_200 >

[Kosta-Github]

@Markionium based on your comments, I am not sure if I should change something in this PR to get it accepted...

[Kosta-Github]

@Markionium can you please check again?

[Markionium]

Thanks a lot!

[Markionium]

Published as 1.11.0