Name collision on request/response objects

[leeola]

When two routes have the same name for a Request / Response the namespaces are clobbered. Example:

https://github.com/leeola/example_okapi_name_collision (specifically this file) will incorrectly report that the /two route has a response type of:

{
  "reply": "string"
}

Instead of what it should be,

{
  "different_schema": "string"
}

I'm happy to help developing a solution to this, but I'm unsure how best it can be handled. Ideally, I imagine something resembling idiomatic OpenAPI specs should be generated. Though, looking at the classic PetStore example it looks like that entire bottom area is ripe for having many structure names occupy the same namespace.

Thoughts on how best to handle this?

[leeola]

Additionally, I should note that there are two possible areas to fix:

1. In the route section structures can be incorrectly reported. As in the original report.
2. Even if the Schemas section allowed both Response objects to have their own section, it would not be visually clear what Response object each is. Some type of prefix may be desired, eg: /one::Response, /two::Response.

I suppose another option to fixing this would be to provide some form of openapi_struct(rename = "ResponseOne"). While this would work, it would be quite tedious for large projects.

I suppose it depends on what would produce the most idiomatic OpenAPI sheet.

[leeola]

Here is the JSON for reference:

{
  "openapi": "3.0.0",
  "info": {
    "title": "",
    "version": ""
  },
  "servers": [
    {
      "url": "/my_resource"
    }
  ],
  "paths": {
    "/one": {
      "get": {
        "operationId": "handler_one_handler_one",
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Response"
                }
              }
            }
          }
        }
      }
    },
    "/two": {
      "get": {
        "operationId": "handler_two_handler_two",
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Response"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Response": {
        "type": "object",
        "required": [
          "reply"
        ],
        "properties": {
          "reply": {
            "type": "string"
          }
        }
      }
    }
  }
}

[GREsau]

So this is really a shortcoming of schemars, where schemas are given a name which gets appended to #/components/schemas/ (or #/definitions/ for non-openapi schemas). When deriving JsonSchema on a type, the default schema name is simply set to the name of the type, which can indeed cause problems when multiple types have the same name.

This can currently be worked around by adding a #[schemars(rename = "...")] or #[serde(rename = "...")] attribute to one of the types, which will override the schema name:

pub mod handler_two {
    use super::*;

    #[derive(serde::Serialize, schemars::JsonSchema)]
    #[schemars(rename = "Response2")] // <-- add this attribute!
    pub struct Response {
        different_schema: String,
    }

...

It may be possible to improve this in schemars by including the output of module_path!() in the schema name, as long as it doesn't make the names too verbose...I'll have a think about it