swagger-ui - 作为参数传递的 swagger 对象可以在 swagger-ui 中具有默认值吗？

Question

我定义了一个以 MyObject 作为参数的路径。
MyObject 具有猫和狗的属性。这些有默认值。
在 swagger-editor 中，该示例不显示默认值，但试用确实创建了一个具有正确默认值的 MyObject。

在 swagger-ui 中，我可以在 Models 下看到默认值，但在 API 中看不到。有没有办法设置这些默认值？
招摇:'2.0'
信息:
标题:将具有默认属性的对象作为参数传递
说明:等
版本:“草案 0.1.1”
主机:example.com
基本路径:/
产生:
- 应用程序/json

paths:
  /myobject:

     post:
      summary: |
        post an object.
      parameters:
        - name: myObject
          in: body
          required: true
          schema:
            type: array
            items:
              $ref: '#/definitions/MyObject'
      responses:
        200:
          description: OK

definitions:

  MyObject:  # move to/models/model.yml
      type: object
      description: Contains default properties
      required:
        - cats
        - dogs
      properties:
        cats:
          type: number
          default: 9
        dogs:
          type: string
          default: "fido"

Answer 1

您对 default 的使用是错误的。你可能想要 example 代替。
default 仅与 可选字段 一起使用，并且 在服务器端处理 。也就是说，如果客户端未在有效负载中提供值，则服务器将使用 default 值。

考虑这个 User 模型:

definitions:
  User:
    type: object
    required:
      - username
    properties:
      username:
        type: string
      role:
        type: string
        enum:
          - user
          - poweruser
          - admin
        default: user

role 属性是可选的，默认为 user 。因此，如果客户端发送没有 role 的有效负载:

{
  "username": "bob"
}

服务器将假定 role = user 。

在您的情况下，您似乎想要为字段提供示例值。这就是 example 关键字的用途:

definitions:
  MyObject:
    type: object
    description: Contains default properties
    required:
      - cats
      - dogs
    properties:
      cats:
        type: number
        example: 9      # <---
      dogs:
        type: string
        example: fido   # <---