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:
- What is correct format for dates?
- What are possible options for field ‘Type’
- How much decimal point is supported for Value field?
- 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; } }
- Enable XML comments in SwaggerConfig
Uncomment and edit line:c.IncludeXmlComments(System.Web.Hosting.HostingEnvironment.MapPath("~/bin/SwaggerDemo.xml"));
- 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.