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

Question

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

在 swagger-ui 中，我可以在模型下看到默认值，但在 API 中看不到。有没有办法设置这些默认值？大摇大摆：'2.0' 信息： title: 以默认属性作为参数传递 object 描述：等版本："Draft 0.1.1" 主持人：example.com 基本路径：/ 产生： - application/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   # <---

Answer 2

默认好像有两种：

server-side：变量不是必需的，如果未给定，服务器将为其假定一个值 definition from OpenApi v3.0 spec
客户端：变量是必需的，并且只能是一个值（例如headers）

对于 client-side 默认值，我们可以通过设置 required=True 并将枚举设置为唯一允许的值来定义它。请参阅下面的示例：

swagger: "2.0"
info:
  title: "some api"
  description: "a description"
  version: "1.0.0"
host: "example.com"
basePath: "/api"
schemes:
- "http"
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:
      type: object
      description: Contains default properties
      required:
        - cats
        - dogs
      properties:
        cats:
          type: number
          enum:
            - 9
        dogs:
          type: string
          enum:
            - fido

您可以在此处的 swagger-editor 中看到它的工作原理：https://editor.swagger.io/

默认参数有点混乱，因为 swagger 2.0 最初描述默认参数时没有指定服务器或客户端参考框架。

Swagger 2.0 spec 将模式默认定义为

default (Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object)

OpenAPI v3.0 spec

default - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, if type is string, then default can be "foo" but cannot be 1.

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

Can a swagger object passed as a parameter have default values in swagger-ui?

swagger-ui

swagger-2.0

swagger-editor