Provide alternate (international) spelling for defined Swagger route

Question

I'm working on an API spec in swagger that has an endpoint:

/authorizations

I would like to define an alternative spelling (authorisations) for this endpoint as well. Is this possible? Or do I need to define a separate route for each spelling?

/authorizations:
    get:
      description: Returns a list of authorizations

Answer 1

Swagger currently does not support overloading/aliasing path definitions. I don't recall ever seeing such a request, but you're more than welcome on open an issue on https://github.com/wordnik/swagger-spec asking to add support for it in future versions.

Answer 2

A possible workaround is to define another path that $refs the original path, this way you end up with two copies of the same path.

paths:
  /authorizations:
    get:
      description: Returns a list of authorizations
      responses:
        200:
          description: OK
  /authorisations:
    $ref: '#/paths/~1authorizations'

One limitation of this technique is that you cannot have operationId for these paths, because both paths will end up with the same ID, which is not allowed.

If you need to have different operationId in paths, you'll need to define the 2nd path in the usual way (i.e. copy-paste the definition from the 1st path).

Answer 3

See https://github.com/OAI/OpenAPI-Specification/issues/213 where one suggestion is to define a "renamed" path by using a 308 redirect:

  /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

(I've not seen another means to implement this cleanly.)