nullable fields in swagger on node.js

Question

I've spent a bunch of time trying to find a solution for creating swagger docs in Node.JS. The main library is swagger-node, in which you create a swagger yaml file and then add your controllers to it. It automatically provides swagger ui docs in your app and does validation on the request & response against the models you specify in your yaml.

This is neat, however I have a requirement that some fields I want to explicitly be able to return or accept null as a value, for instance:

{ 
  id: 123,
  description: "string",
  date_sent: null
}

I don't want to delete the date_sent key, I want to explicitly state it as null.

The swagger spec does not support anyOf which is how JSON schema normally does this I believe.

I'm wondering if there's a workaround? Perhaps some library available for node that has a x-nullable vendor specific flag you can add, or some way of specifying that my not-required fields should all be nullable.

Am I going to have to write something myself that takes my swagger file and then modifies it before the validator middleware runs, or is there some workaround someone can suggest?

Answer 1

nullable field is supported in OpenAPI (fka Swagger) Specification v3.0.0 , but not in v2.0. Nullable types are defined as follows:

# Can be string or null
type: string
nullable: true

Answer 2

SwaggerUI doesn't support nullable types (please, see here ). But I used nullable properties as:

type: ['string','null']

After that this property disappears from UI, but validation still worked.

Answer 3

Instead of add null in type property, you can use default property instead.

Swagger.json property definition example:

"due_date": {
  "type": "string",
  "description": "Due date",
  "default": "null"
},

It's a valid Swagger type definition, and still appears as expected in Swagger UI.

Answer 4

Just as a hint, because I stumpled upon this: When I added

type: string
nullable: true`

as described in the answer https://stackoverflow.com/a/42797352/2750563 my service returned only "fieldName": { "present": true } instead of an actual value!

If you see this, simply add the JsonNullableModule to your Jackson serializer, for example, if using Spring:

@Component
public class JacksonConfiguration {

    @Autowired
    public void configureJackson(ObjectMapper mapper) {
        mapper.registerModule(new JsonNullableModule());
    }

}

Then everything looks fine again.