ASP.NET Web API documentation using Swagger – Introduction

Providing always up-to-date and exhaustive documentation for your WEB API could be quite a challenging task.
Swagger and Swashbuckle did a great job to provide uniform documentation for any kind of API.
Let’s look into this using simple demo discount API example.

Setup ASP.NET WEB API project

First, create empty ASP.NET Web API project.
Add new controller – DiscountController inside Controllers folder.

using System;
using System.Web.Http;
using SwaggerDemo.Models;

namespace SwaggerDemo.Controllers
{
    public class DiscountController : ApiController
    {
        [Route("discounts")]
        public IHttpActionResult Post(DiscountModel model)
        {
            model.Id = 2017;
            return Created("", model);
        }

        [Route("discounts/{id}")]
        public IHttpActionResult Get(int id)
        {
            return Ok(new DiscountModel
            {
                Id = id,
                StartDate = new DateTime(2017, 10, 31),
                EndDate = new DateTime(2019, 10, 31),
                Type = "PercentOff",
                Value = 35
            });
        }
    }
}


DiscountModel class:

using System;

namespace SwaggerDemo.Models
{
    public class DiscountModel
    {
        public int Id { get; set; }
        public DateTime StartDate { get; set; }
        public DateTime EndDate { get; set; }
        public string Type { get; set; }
        public decimal Value { get; set; }
    }
}

Now if we run F5 or Debug in Visual Studio, our new API is accessible at http://localhost:50217/discounts/25 (50217 is port number, could be different on your machine)

Add Swashbuckle to the project

Swashbukle page says: Seamlessly adds a swagger to WebApi projects! And it works in that way, all you need is to install it from Nuget and you are ready to start.
Now rerun application, you could now access SwaggerUI page by http://localhost:50217/swagger/ui/index

Add more documentation

Let’s look into what Swashbuckle generated by default. First look at model:

Questions that immediately appear if want to start using API:

  1. What is correct format for dates?
  2. What are possible options for field ‘Type’
  3. How much decimal point is supported for  Value field?
  4. What fields are really optional?

Let’s try to answer all those questions by providing XML comments for model properties.

    public class DiscountModel
    {
        /// <summary>
        /// Discount unique Id, auto-generated
        /// </summary>
        public int Id { get; set; }

        /// <summary>
        /// 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.
        /// </summary>
        [Required]
        public DateTime StartDate { get; set; }

        /// <summary>
        /// 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.
        /// </summary>
        [Required]
        public DateTime EndDate { get; set; }

        /// <summary>
        /// Possible values are: PercentOff and MoneyOff
        /// </summary>
        [Required]
        public string Type { get; set; }

        /// <summary>
        /// Max number of decimal places is 2. E.g. provided 35.355 will be truncated to 35.35.
        /// </summary>
        [Required]
        public decimal Value { get; set; }
    }
  1. Enable XML comments in SwaggerConfig
    Uncomment and edit line:

    c.IncludeXmlComments(System.Web.Hosting.HostingEnvironment.MapPath("~/bin/SwaggerDemo.xml")); 
  2. Enable XML documentation output during project build
    Go Project Properties => Build section => Check XML documentation file checkbox.

Let’s build and run the project, now model looks much nicer providing guidance on how to use discount model.

Summary:

Enabled Swagger documentation for Web API project.
Added model property XML comments to provide information about expected input options and its format.
Used DataAnnotations to document required model properties.

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 )

Google+ photo

You are commenting using your Google+ 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 )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.