Example null values ignored by ExampleBuilder

[richard-walsh-sb]

When using in null values in example schemas the result returned by ExampleBuilder is not returning true null values. There seems to be a couple of things at play here.

The first is that if a StringExample is null the default value "string" is returned so for the following spec we don't get the expected null value returned:

paths:
  /object-with-null-example:
    get:
      description: Response should be `null`
      responses:
        '200':
          description: Should be `null`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectWithNullExample'
components:
  schemas:
    ObjectWithNullExample:
      type: object
      properties:
        foo:
          type: string
      nullable: true
      example: null

Expected return value:

null

Actual return value

{
  "foo" : "string"
}

The second issue seems to be arising from io.swagger.v3.core.util.Json.pretty(java.lang.Object) where null values are being returned as a string of value "null". For example:

paths:
  /object-with-null-in-schema-example:
    get:
      description: 'Response should be `{..., "d": null}`'
      responses:
        '200':
          description: 'Should be `{..., "d": null}`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectWithNullInSchemaExample'
components:
  schemas:
    ObjectWithNullInSchemaExample:
      type: object
      example:
        a: 5
        b: test
        c: true
        d: null

Expected return value:

{
  "a" : 5,
  "b" : "test",
  "c" : true,
  "d" : null
}

Actual return value

{
  "a" : 5,
  "b" : "test",
  "c" : true,
  "d" : "null"
}

I have created a failing unit test that demonstrates this behaviour and more examples here -> #370

[frantuma]

handled/fixed in #375, where some changes have been introduced (fixes and/or workarounds)

Going through the use cases of the test PR (also available in the merged PR):

1st case:

• object-with-null-example
• object-with-null-property-example
• string-with-null-example
• array-with-null-array-example
• array-with-null-item-example

we cannot easily handle and we won't, we cannot differentiate between missing and null examples; this is a general (i.e. not limited to swagger) known issue usually in scope of applying patches/updates, and has no simple solution
Applying some solution to allow to differentiate implicit nulls (missing) from explicit would involve at least break models/core/parser compatibility or at least some serious effort (e.g. applying/processing "set flags" in all the tool chain).

In order to work around this issue if badly needed, we have introduced processing of an extension x-inflector-null-example which would mark the specific schema to have its example resolved as null if that is null.

The call is activated by calling ExampleBuilder with the additional parameter processNullExtension as true

There is another added parameter nullExample which would return null for any example which is null (therefore also without extension), but this is probably not really useful as it will also return null for any non defined example

see the test and the test definition in the PR for usage.

2nd case:

• object-with-null-in-schema-example
• array-with-null-in-array-example

These cases were different than the first case, and a fix has solved them.

UPDATE

specific update of tool chain (swagger-core and swagger-parser) for the example field alone to implement the "set flag" mentioned above turned out to be somehow easier than expected, and PR #377 will add support for null examples without needing extensions; this will be merged when an unrelated issue with tests and latest parser version gets fixed (#376)

related PRs:

• implements exampleSetFlag to flag deserialization of null example vs missing swagger-core#3637
• process exampleSetFlag to flag deserialization of null example vs missing swagger-parser#1400
• refs #371 - better null example handling using updated core and parser - also update dependencies #377