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?

Related: [How to define a property that can be string or null in OpenAPI (Swagger)?](https://stackoverflow.com/q/48111459/113116), [How to specify a property can be null or a reference with Swagger?](https://stackoverflow.com/q/40920441/113116) — Helen, Aug 15 '18 at 07:37

score 21 · Answer 1 · edited Jan 05 '18 at 13:30

21

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

edited Jan 05 '18 at 13:30

Helen

87,344
17
243
314

answered Mar 14 '17 at 21:59

Naz

5,104
8
39
63

Instead of the actual value, I now get `"fieldName": {"present":true}` when I retrieve the data. How do I get the value back into the output? – konse Nov 26 '19 at 08:49
--> posted a solution for this problem: https://stackoverflow.com/a/59047331/2750563 – konse Nov 26 '19 at 09:12

score 15 · Accepted Answer · answered Jul 01 '16 at 08:27

15

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.

answered Jul 01 '16 at 08:27

Sergiy

611
7
16

3

aha! I tried this, but in yaml I did `string` and `null` but you have to have quotes around the `'null'` for it to work. Thanks! Also, if you add a 'default' then it will show up again in the example values, I guess it just doesnt know which one to use as an example – RodH257 Jul 04 '16 at 00:28
Wow! Thanks so much! I didn't think about default value. I will try it for my project – Sergiy Jul 04 '16 at 03:54
4

That's not a valid Swagger type definition, by the way. – Ron Jul 12 '16 at 22:56
As Ron said, this is not valid in OpenAPI/Swagger. [Nazar Gargol's answer](https://stackoverflow.com/a/42797352/113116) is the correct one. See also [How to define a property that can be string or null in OpenAPI (Swagger)?](https://stackoverflow.com/q/48111459/113116). – Helen Jan 05 '18 at 13:32
FYI this will make properties with this type not appear in the output of `swagger-codegen` which is one of the most useful tools for Swagger specifications. – jshbrntt Jan 18 '18 at 10:48

score 5 · Answer 3 · answered Dec 07 '17 at 05:59

5

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.

answered Dec 07 '17 at 05:59

Noval Parinussa

84
2
3

Genius answer for Swagger 2 - no idea why this has not been upvoted - many thanks – danday74 Apr 11 '18 at 08:59
On further research, whilst this seems to work fine, sadly it gives an error in the swagger editor – danday74 Apr 11 '18 at 09:34
3

This definition is only valid because it uses the string `"null"`, not the actual `null`. This is not what the OP wants. – Helen Apr 26 '18 at 18:54
Btw, `default: null` (using the actual `null` not the string `"null"`) is not valid in OpenAPI 2.0. The Specification [says](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#schema-object) the `default` value "MUST conform to the defined type" - but `null` does not conform to the `string` type and there's also no `null` type in OpenAPI 2.0. [Nazar Gargol's answer](https://stackoverflow.com/a/42797352/113116) is the only correct answer here. – Helen Apr 26 '18 at 18:57

score 2 · Answer 4 · answered Nov 26 '19 at 09:10

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.

nullable fields in swagger on node.js

4 Answers4

Linked