日期时间空模型架构显示 swashbuckle + swagger ui

Question

I have implemented Swashbuckle and Swagger UI to do my API documentation.

I'm having a problem with correctly displaying a nullable DateTime , or any nullable object for that matter.

Currently a nullable DateTime displays as "date": "2016-05-27T00:15:41.658Z" in the response model schema.

The response model displays the date as date (string, optional) which states that it's optional, but it also displays that for a non-nullable DateTime .

I've tried to add default value via: Default model example in Swashbuckle (Swagger) and also tried to add a model schema example via the last answer.

Any ideas on how I can get "date": "null" to display in the model schema? Or alternatively find a better way to give the person reading the documentation an indication that the date object can be null?

Answer 1

The short answer

You can't and you shouldn't

The slightly longer answer

Basically the documentation provided, date (string, optional) , is already telling your consumers that the property can be null or missing in a request or a response. So, providing an example with "date": null isn't very helpful. Providing an example with a valid date, however, is helpful: it gives the consumer an idea of what the date looks like.

Now, on to the DateTime and DateTime? properties server side. When the server receives an object with a missing date, the type of the property determines the value. When a property with type DateTime is missing, ASP.Net Web API will set that property to the minimal date (01-01-0001Z00:00:00). However, when a property with type DateTime? is missing, ASP.Net Web API will set that property to null.

The same goes for the response sent by the server. When the server sends an object with a property of type DateTime it will always send a value. However, when a property with type DateTime? is send, the sent property will only have a value when `HasValue' of the property is true. Otherwise the response won't have the property.