Swagger 2.0：具有不同路径但请求和响应相同的多个 Path 对象答案

【问题标题】：Swagger 2.0: Multiple Path objects with different paths but same request and responseSwagger 2.0：具有不同路径但请求和响应相同的多个 Path 对象
【发布时间】：2017-05-24 06:39:54
【问题描述】：

由于某些向后兼容的原因，我需要同时支持/ab 和/a-b 这两个路径。

两个路径的请求和响应对象将是相同的。

我是否可以在我的 Swagger 规范中包含类似以下内容，这样我就不必为两个路径重复请求和响应对象定义。

paths:
  /ab:
  /a-b:
    post:
    ...

【问题讨论】：

标签： swagger swagger-2.0 openapi

【解决方案1】：

是的，你可以有一个引用另一个路径项的路径项：

paths:
  /ab:
    post:
      summary: ...
      ...
      responses:
        ...

  /a-b:
    $ref: '#/paths/~1ab'   # <------------

这里，~1ab 是/ab 的编码版本（见下文）。

此方法的一个限制是您不能在引用路径项的所有操作中都有operationId。这是因为路径的副本最终具有相同的 operationId 值，但 operationId 必须是唯一的。

编码 $ref 值

如果字符 ~ 和 / 出现在节点名称中（如路径名称的情况，例如 /ab），它们必须被编码：~ 为 ~0，/ 为 @ 987654334@:

/ab → ~1ab → $ref: '#/paths/~1ab'
/foo/bar → ~1foo~1bar → $ref: '#/paths/~1foo~1bar'
/ab~cd → ~1ab~0cd → #/paths/~1ab~0cd

此外，{} 和 URI 片段标识符 (RFC 3986, section 3.5) 中不允许使用的其他字符需要进行百分比编码。例如，{ 变为 %7B，} 变为 %7D。

/{zzz}
→ ~1{zzz} ( / 替换为 ~1)
→ ~1%7Bzzz%7D（百分比编码）
→$ref: '#/paths/~1%7Bzzz%7D'
/foo/{zzz}
→ ~1foo~1{zzz} ( / 替换为 ~1)
→ ~1foo~1%7Bzzz%7D（百分比编码）
→$ref: '#/paths/~1foo~1%7Bzzz%7D'

请注意，您只需要编码路径名而不是 #/paths/ 前缀。

【讨论】：

路径也有一些模板字符，例如：paths: /ab/{c}/{d}。从/a-b引用时，花括号是否也需要转义？
@Helen 这似乎不再是真的了。使用 openapi 3 大括号招摇给了我一个语法错误（虽然令人惊讶地工作......？）。错误是$ref values must be RFC3986-compliant percent-encoded URIs。要修复此错误，请将{ 替换为%7B，将} 替换为%7D。
@UeliDeSchwert 你是对的。我更新了答案。
@DaveyBoy 这在 OpenAPI 2.0 和 3.0 中都受支持。
@SamuelO.D.没有解决方法。正如答案中所解释的 - “这种方法的一个限制是您不能在引用路径项的所有操作中拥有operationId。这是因为路径的副本最终具有相同的operationId值，但operationId 必须是唯一的。”