Question

在Swagger 2.0（OpenAPI规范）中，有任何方法可以指定＆＃34;示例＆＃34;对于请求正文并指定参考？我可以为响应机构这样做。我的情况是针对某个PUT，正文是一个引用，但是您放置的实例会与架构的示例值不同。

 - name: myObj
   in: body
   description: The information
   required: true
   schema:
     $ref: '#/definitions/SomeObject'
     example: 'some string that conforms to my ref'

Answer 1

在OpenAPI 2.0中 - 不，不是真的。 $ref会覆盖任何相邻的关键字，因此example将被忽略。某些工具支持x-example或x-examples参数，因此取决于您可能能够使用的工具

 - name: myObj
   in: body
   description: The information
   required: true
   schema:
     $ref: '#/definitions/SomeObject'
   x-example:
     property1: value1
     property2: value2

或

 - name: myObj
   in: body
   description: The information
   required: true
   schema:
     $ref: '#/definitions/SomeObject'
   x-examples:
     application/json:
       property1: value1
       property2: value2

或类似的东西。

你想要的是 OpenAPI 3.0 ：

openapi: 3.0.0
...

paths:
  /something:
    put:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SomeObject'
            example:
              property1: value1
              property2: value2

Swagger UI 3.17.4及更高版本支持此功能。

Swagger 2.0请求正文使用ref和example

1 个答案: