为定义的 Swagger 路线提供替代（国际）拼写答案

【问题标题】：Provide alternate (international) spelling for defined Swagger route为定义的 Swagger 路线提供替代（国际）拼写
【发布时间】：2015-01-16 06:18:48
【问题描述】：

我正在使用 swagger 编写具有端点的 API 规范：

/authorizations

我也想为此端点定义一个替代拼写（授权）。这可能吗？还是我需要为每个拼写定义单独的路线？

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

【问题讨论】：

标签： swagger openapi swagger-2.0

【解决方案1】：

一种可能的解决方法是定义另一个路径 $refs the original path，这样您最终会得到相同路径的两个副本。

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

此技术的一个限制是您不能为这些路径使用operationId，因为这两条路径最终将具有相同的 ID，这是不允许的。

如果您需要在路径中有不同的operationId，则需要以通常的方式定义第二个路径（即从第一个路径复制粘贴定义）。

【讨论】：

【解决方案2】：

Swagger 当前不支持重载/别名路径定义。我不记得曾经见过这样的请求，但是非常欢迎您在 https://github.com/wordnik/swagger-spec 上打开一个问题，要求在未来的版本中添加对它的支持。

【讨论】：

【解决方案3】：

请参阅https://github.com/OAI/OpenAPI-Specification/issues/213，其中一个建议是使用 308 重定向定义“重命名”路径：

  /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

（我还没有看到另一种干净利落地实现的方法。）

【讨论】：