Swagger 2.0:具有不同路径但请求和响应相同的多个Path对象 [英] Swagger 2.0: Multiple Path objects with different paths but same request and response

问题描述

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

Due to some backward compatibility reasons, I need to support both the paths /ab and /a-b.

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

The request and response objects are going to be the same for both of the paths.

我的Swagger规范中可以包含以下内容吗，这样我就不必为两个路径都重复请求和响应对象的定义了.

Can I have something like the following in my Swagger spec so that I do not have to repeat the request and response object definitions for both the paths.

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

推荐答案

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

Yes, you can have a path item reference another path item, like this:

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

在这里，~1ab是/ab的转义版本.

Here, ~1ab is an escaped version of /ab.

在JSON指针中，有两个特殊字符需要转义才能按字面解释:~变为~0，而/变为~1:

In JSON pointers, there are two special characters that need to be escaped to be interpreted literally: ~ becomes ~0 and / becomes ~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}

• /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必须唯一.

One limitation of this approach is that you cannot have operationId in all operations of the referenced path item. This is because the copy of the path ends up with the same operationId values, but operationId must be unique.

这篇关于Swagger 2.0:具有不同路径但请求和响应相同的多个Path对象的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！