swagger-core

swagger-core copied to clipboard

Expected Behavior

According to the OpenAPI specification I should be able to write an OpenAPI document that contains null values.

See for reference: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#data-types https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#schemaNullable

Current Behavior

If I write the OpenAPI document completely by hand (programmatically or the text document itself) it works without any problems but when I use POJO classes that contains fields annotated with @Schema e.g.: @Schema(nullable = true, example = "null", defaultValue = "null") it doesn’t always work correctly.

After serialization in the OpenAPI document some fields don’t have an example and default property at all, and others have converted null values. For the following data types from a "null" string it produces:

• integer, number
  • No example
• string
  • "null" string
• boolean
  • false
• object, array:
  • null, It works as expected

I’ve noticed that regardless of the nullable property only the object data type works correctly. The array data type only works correctly with the example property.

Possible Solution

Annotation processing should respect the nullable property and if that is true and the example and/or defaultValue property is "null”: it should produce in the OpenAPI document an example and/or default with a null value regardless of the annotated field's data type.

Steps to Reproduce

1. Annotate a POJO class field with type: String, Integer, BigDecimal, Boolean etc. (excluding object and array data types) with @Schema(nullable = true, example = "null", defaultValue = "null").
2. After serialization in the OpenAPI document it should produce incorrect or missing example and default fields.

I’ve created an example web project to test this: https://github.com/bodzso/swagger-nullable-test

Context (Environment)

I’m trying to generate an OpenAPI document from POJOs and endpoints. Currently I cannot produce working requests that works with swagger-ui because of the errors described above. As far as I know it isn’t possible to disable default value generation in swagger-ui and with the above errors combined I didn’t find a possible workaround. Writing the entire OpenAPI document by hand isn’t feasible because the generated one is over a thousand lines.

I’d like to achieve a simple thing: don’t send some optional (nullable) fields in certain examples and don't hide (@Schema(hidden = true)) these fields from the "Schemas".

This issue could be related to: #4229

Will this be fixed?