Openapi-specification: Allow for overloading/aliasing of route path

[brandonscript]

Per this question: http://stackoverflow.com/questions/27004847/provide-alternate-international-spelling-for-defined-swagger-route/27013027#27013027

It would be great to allow aliasing of route paths for such uses as international spellings of words

[MattSANU]

I think that my change in #440 would also address this use case.

[brandonscript]

Nice! Looks like it.

[webron]

Looking back at the question and the reply (SO), there's potentially a way to do that with 2.0 but it may not be a convenient way in some cases. Let's revisit this.

Parent: #560.

[fehguy]

Propose rejecting this per #639

[brandonscript]

Not clear how setting allowed languages would solve the problem of internationalized spellings for routes? If you can elaborate, that'd be great.

[webron]

It's not, but this feels a bit of a niche case that doesn't warrant special treatment. Since Path Item Object can be referenced, it should suffice for this case.

Voting to reject explicit support for this.

[ePaul]

If we reject building in something for this, could we at least document the workaround here (with an example YAML)?

[DavidBiesack]

I've also wanted a solution for this, not so much for internationalized variants, but for normal API evolution. For example, a path is called x, but after feedback from your users, you (they) decide it should really be called y. To avoid a breaking change, it would be better to declare x is an alias for y (or y is an alias for x) and mark x as a deprecated operation. One could even hide or suppress the doc for x (in Swagger UI for example), but code generation or generated SDKs or other tools could route requests correctly (i.e. a generated handler/controller could return a 301 Moved Permanently, or simply call the new implementation).

Note that a simple $ref "solution" is less than ideal because one might want to define more than just reuse - marking an operation as deprecated or adding other x- extensions would be useful/necessary, but using $ref may prohibit that since a reference object may contain only the $ref property and no others.

[brandonscript]

Agreed David, I wonder if this belongs in a new thread as a proper feature request?

[DavidBiesack]

@grapefruit since this is already tagged at "OpenAPI.Next Proposal" and remains Open, this ticket should suffice. If think adding another won't help.

[flaschenpost]

[Update: obsolete, I had just some different error in my .yaml ]
Sorry if I'm wrong, but I would like to use this feature also for format spec. In http://wiki.open311.org/GeoReport_v2/ you can choose between xml and json via suffix. I don't get how to put it in route (/services.{format} does not work), so I would like to make a route /services and a route /services.xml and a route /services.json, which is an alias for services?format=json

[MikeRalphson]

/services.{format} should work fine with whatever tools you're using, as long as you define a matching format parameter which is in: path.

[flaschenpost]

There must have been a different error in my .yaml, now it works like expected! Thanks very much for the very fast response andI wish all the programmers a happy new year!

[vladcomp]

I'm researching migrating our existing API to OpenAPI, and this would be a killer feature to help with migration.

[biomadeira]

Also looking for this feature!

[mattbishop]

I think you would have to redefine the original X like this:

  /original-x:
    description: Redirects to the new X
    get:
      responses:
        '308':
          description: This resource has been moved
          headers:
            Location:
              schema:
                type: string
                default: /new-x