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

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必须是唯一的。
编码 $ref 值
如果字符 ~和 /出现在节点名中(如路径名的情况，例如 /ab )它们必须被编码: ~如 ~0 , 和 /如 ~1 :

/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/ 进行编码。字首。