nullable fields in swagger on node.js

问题:

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?

回答1:

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.

回答2:

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

回答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.