Can a swagger object passed as a parameter have default values in swagger-ui?
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 # <---
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.