Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

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

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:
    ...
like image 305
bdev03 Avatar asked May 24 '17 06:05

bdev03


People also ask

What is the difference between a path and an operation in the OpenAPI specification?

In OpenAPI terms, paths are endpoints (resources), such as /users or /reports/summary/ , that your API exposes, and operations are the HTTP methods used to manipulate these paths, such as GET, POST or DELETE.

How do you mark deprecated in swagger?

There is no special attribute which can mark service endpoint to show it as deprecated in swagger schema, but you can use OperationFilter action when register SwaggerFeature to modify swagger declarations and set Deprecated property to string “true” for obsolete methods.


1 Answers

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.

like image 120
Helen Avatar answered Oct 12 '22 00:10

Helen