12

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.

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:
    ...
Helen
  • 87,344
  • 17
  • 243
  • 314
bdev03
  • 375
  • 1
  • 4
  • 19

1 Answers1

20

Yes, you can have a path item that references another path item:

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

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

Here, ~1ab is an encoded version of /ab (see below).

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.

Encoding $ref values

If the characters ~ and / are present in node names (as in case of path names, e.g. /ab) they must be encoded: ~ as ~0, and / as ~1:

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

Additionally, { } and other characters not allowed in URI fragment identifiers (RFC 3986, section 3.5) need to be percent-encoded. For example, { becomes %7B, and } becomes %7D.

  • /{zzz}
    → ~1{zzz} ( / replaced with ~1)
    → ~1%7Bzzz%7D (percent-encoded)
    → $ref: '#/paths/~1%7Bzzz%7D'
  • /foo/{zzz}
    → ~1foo~1{zzz} ( / replaced with ~1)
    → ~1foo~1%7Bzzz%7D (percent-encoded)
    → $ref: '#/paths/~1foo~1%7Bzzz%7D'

Note that you need to encode just the path name and not the #/paths/ prefix.

Helen
  • 87,344
  • 17
  • 243
  • 314
  • The path also has some template characters like: `paths: /ab/{c}/{d}`. When it is referred from `/a-b`, do the curly braces also need to be escaped? – bdev03 May 24 '17 at 22:54
  • @bdev03: No, curly braces are fine. Only `/` and `~` need to be escaped. – Helen May 25 '17 at 07:51
  • 1
    @Helen this appears not to be true anymore. With curly brackets swagger with openapi 3 gave me a syntax error (while surprisingly working nevertheless...?). The error was `$ref values must be RFC3986-compliant percent-encoded URIs`. To fix this error, replace `{` with `%7B` and `}` with `%7D`. – UeliDeSchwert Jun 09 '20 at 10:22
  • 1
    @UeliDeSchwert You are right. I updated the answer. – Helen Jun 09 '20 at 19:12
  • Is this only for OpenAPI 3.0 ? We're on 2.0 here. – DaveyBoy Aug 27 '20 at 19:05
  • 1
    @DaveyBoy This is supported in both OpenAPI 2.0 and 3.0. – Helen Aug 27 '20 at 22:20
  • Using OpenAPI 2.0 and the python-flask server the validation fails with the error "swagger_spec_validator.common.SwaggerValidationError: Duplicate operationId". Is there a way around this? – Samuel O.D. Jan 25 '21 at 09:27
  • 1
    @SamuelO.D. No workaround. As explained in the answer - *"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."* – Helen Jan 25 '21 at 10:10