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

Question

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

在swagger-ui中，我可以在Models下看到默认值，但在API中看不到。有没有办法设置这些默认值？swagger：'2.0‘info: title:使用默认属性作为参数传递对象描述: etc版本："Draft 0.1.1“主机: example.com basePath: / produces：- 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

似乎有两种默认值：

• 服务器端:变量不是必需的，如果没有指定definition from OpenApi v3.0 spec
• client端，服务器将使用一个值: variable是必需的，并且只能是一个值(例如headers)

对于客户端默认值，我们可以通过将required=True和enum设置为唯一允许的值来定义它。请参见下面的示例：

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编辑器中看到它的工作方式：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.