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

Question

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

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

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

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

Answer 1

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

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

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

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

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

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

此外，{ } 和 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/ 前缀。

Swagger 2.0: Multiple Path objects with different paths but same request and response