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

Question

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

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

我可以在Swagger规范中添加以下内容吗，这样我就不必在两个路径上都重复请求和响应对象的定义。

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

Answer 1

是的，您可以让一个路径项目引用另一个路径项目，如下所示：

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

这~1ab是的转义版本/ab。

在JSON的指针，有需要进行转义从字面上解释了两个特殊字符：~变成~0和/变成~1：

• /ab？~1ab？$ref: '#/paths/~1ab'
• /foo/bar？~1foo~1bar？$ref: '#/paths/~1foo~1bar'
• /ab~cd？~1ab~0cd？#/paths/~1ab~0cd
• /ab/{c}/{d}？~1ab~1{c}~1{d}？#/paths/~1ab~1{c}~1{d}

这种方法的局限性在于您不能operationId对引用的路径项进行所有操作。这是因为路径的副本最终具有相同的operationId值，但operationId必须是唯一的。