Nullable properties with default of null are interpreted incorrectly

[johncmunson]

The Swagger UI seems to parse nullable properties that have a default value of null incorrectly.

Take this note property for example...

note:
  type: string
  nullable: true
  default: null

If you look at the GET /todos/{id} route in my swagger todo-api and use the "Try it out" feature, you'll see this as a sample response...

{
  "id": 0,
  "title": "string",
  "complete": false,
  "archived": false,
  "note": "string",
  "dueDate": "string",
  "priority": "medium",
  "categoryId": 0
}

It looks like Swagger is interpreting the default value of note as the string "null", rather than the null datatype. Furthermore, it seems that categoryId (which is also nullable and has a default value of null) is getting the default value of 0 instead.

The OpenAPI 3.0 is admittedly vague in regards to the interaction of nullable properties and their default values, which is why I opened up this issue in their repo, but Ted Epstein replied with what should be the correct interpretation and verified that this issue will be clarified more concretely in OpenAPI v3.0.3.

[hkosova]

@joelittlejohn you wrote

It looks like Swagger is interpreting the default value of note as the string "null", rather than the null datatype.

but the example displayed in Swagger UI contains "note": "string" not "note": "null". Is this a typo?

Anyway, the schema example displayed by Swagger UI matches the schema definition, there's no error here.

Please note that the default value is NOT an example value - it's the value that will be assumed by the recipient of the payload if the value is not provided in the payload. To specify example values for documentation purposes, use example instead.

If you change the definition to

note:
  type: string
  nullable: true
  default: null
  example: null  # <---

then UI will display "note": null.

[johncmunson]

@hkosova I posted this a little while ago, but I can see I must've been a bit confused at the time because the sample code I provided definitely doesn't match what I was describing, sorry!

Anyways, thank for clarifying and pointing out "example"!