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

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），它们必须被编码：~as~0和/as ~1：

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

此外， URI 片段标识符（ RFC 3986，第 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/前缀。