Can a swagger object passed as a parameter have de

问题:

I define a path that takes MyObject as a parameter. MyObject has properties for cats and dogs. These have default values. In swagger-editor, the example doesn't show the default values, but try-it-out does create a MyObject with correct defaults.

In swagger-ui, I can see the defaults under Models, but not in the API. Is there a way to set these defaults ? swagger: '2.0' info: title: pass object with default properties as a parameter description: etc version: "Draft 0.1.1" host: 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"

回答1:

Your usage of default is wrong. You probably want example instead.

default is only used with optional fields and is handled on the server side. That is, if the client does not supply a value in the payload, the server will use the default value.

Consider this User model:

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

The role property is optional and defaults to user. So, if the client sends the payload without role:

{
  "username": "bob"
}

the server will assume role=user.

In your case, it looks like you want to provide example values for the fields. This is what the example keyword is for:

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

回答2:

It seems like there are 2 kinds of defaults:

• server-side: variable is not required and server will assume a value for it if it is not given definition from OpenApi v3.0 spec
• client side: variable is required and must be only one value (for example headers)

For a client-side default, we can define it by setting required=True and enum to the only allowed value. See this example below:

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

And you can see it work in the swagger-editor here: https://editor.swagger.io/

The default parameter is a bit confusing because swagger 2.0 initially described the default parameter without specifying a server or client reference frame.

Swagger 2.0 spec Defines schema default as

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.