在Swagger YAML定义中,有没有办法避免HTTP方法之间的重复?

时间:2017-06-07 13:06:37

标签: swagger swagger-2.0

我正在编写一个API规范,我希望PUT和PATCH功能完全相同。 API无论是接收PUT还是PATCH请求都无关紧要。它会做同样的事情。

是否有一个速记/参考语法可以阻止我从PUT方法定义复制和粘贴参数和响应等到PATCH方法定义?

1 个答案:

答案 0 :(得分:1)

没有

尽管OpenAPI(fka Swagger)规范2.0在API定义的某些地方支持$ref,但在操作级别上不支持它。因此,您需要为PUT和PATCH分别定义。您可以通过$ref每个操作中的参数和响应来减少代码重复。

paths:
  /foo:
    # If ALL operations within a path have some common parameters,
    # define these params on the path level instead
    # parameters:
    #  - $ref: '#/parameters/baz'

    put:
      parameters:
        - $ref: '#/parameters/baz'
      responses:
        200:
          $ref: '#/responses/Success'
        default:
          $ref: '#/responses/Error'
    patch:
      parameters:
        - $ref: '#/parameters/baz'
      responses:
        200:
          $ref: '#/responses/Success'
        default:
          $ref: '#/responses/Error'

parameters:
  baz:
    in: query
    name: baz
    type: string

responses:
  Success:
    description: Operation completed successfully
    schema:
      type: object
      ...
  Error:
    description: Error response
    schema:
      type: object
      ...