ASP.NET Web API documentation using Swagger – Use schema mapper for generic data types

If get back to previous post, you could see that descriptions for StartDate and EndDate are duplicated.
DateTime description shall be consistent across all API, so to not repeat yourself let’s use MapType feature of Swashbuckle configuration.

Open SwaggerConfig and find section with c.MapType (it is commented by default). Now let’s map DateTime to the specific schema:

c.MapType<System.DateTime>(() => new Swashbuckle.Swagger.Schema
{
    type = "string",
    format = "date-time",
    description = 
        @"Date-time string in <a href=""https://en.wikipedia.org/wiki/ISO_8601#UTC\"">ISO 8601 format</a>.
          Date-time without time-zone is treated as UTC."
});

Now, we could remove explicit descriptions from DiscountModel:

[Required]
public DateTime StartDate { get; set; }

[Required]
public DateTime EndDate { get; set; }

If now open Swagger page, you will see consistent descriptions for DateTime field:

One more thing is that you could override the description by using XML comments over the model property:

/// 
<summary>
/// Overriden description
/// </summary>

[Required]
public DateTime StartDate { get; set; }

Now Swagger-UI page looks like this:

This entry was posted in Documentation, WEB API and tagged , . Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s