Documenting ASP.NET REST APIs with Swagger

Web API v2 has made ASP.net a great choice for building REST APIs, but great APIs need great documentation. In this post, we'll look at how to add auto-generated documentation seamlessly to our Web APIs.

In the REST API world, there is something called the Swagger Project. A Swagger specification is a language-agnostic way to describe your REST API. In most popular web stacks, there are tools to generate and consume Swagger specs and .net is no exception. Enter Swashbuckle, an amazing open-source .net integration library for Swagger. Swashbuckle performs two main tasks:

1. Automatically generate a swagger specification from your OWIN assemblies.
2. Host a web page for displaying the documentation.

Without further delay, let's dive into the code. Open Visual Studio and create a new Console Project. Ahh... that new project smell. Next, add two NuGet references from the Package Manager Console:

Install-Package Microsoft.Aspnet.WebAPI.OwinSelfHost
Install-Package Swashbuckle.Core

With these two packages installed, let's move on to define our OWIN entry point. Add a new class to the project called "Startup" (Startup.cs) and paste the following code:

using System.Collections.Generic;
using System.Net.Http.Formatting;
using System.Web.Http;
using Newtonsoft.Json;
using Newtonsoft.Json.Converters;
using Newtonsoft.Json.Serialization;
using Owin;
using Swashbuckle.Application;

namespace OwinSwagger
{
    public class Startup
    {
        public void Configuration( IAppBuilder app )
        {
            var config = new HttpConfiguration();

            //Use JSON friendly default settings
            var defaultSettings = new JsonSerializerSettings
            {
                Formatting = Formatting.Indented,
                ContractResolver = new CamelCasePropertyNamesContractResolver(),
                Converters = new List<JsonConverter>{ new StringEnumConverter{ CamelCaseText = true }, }
            };
            JsonConvert.DefaultSettings = () => { return defaultSettings; };

            //Specify JSON as the default media type
            config.Formatters.Clear();
            config.Formatters.Add( new JsonMediaTypeFormatter() );
            config.Formatters.JsonFormatter.SerializerSettings = defaultSettings;

            //Route all requests to the RootController by default
            config.Routes.MapHttpRoute( "api", "{controller}/{id}", defaults: new { id = RouteParameter.Optional } );
            config.MapHttpAttributeRoutes();

            //Tell swagger to generate documentation based on the XML doc file output from msbuild
            config.EnableSwagger( c =>
            {
                c.IncludeXmlComments( "docs.xml" );
                c.SingleApiVersion( "1.0", "Owin Swashbuckle Demo" );
            } ).EnableSwaggerUi();

            app.UseWebApi( config );
        }
    }
}

The names of the class (Startup), method (Configure), and parameters (IAppConfig) are all OWIN conventions and must be left intact for this example. Most of the code above is telling OWIN to use sensible defaults for returning human-readable JSON from the APIs. Toward the end of the function, EnableSwagger() tells Swashbuckle to ingest a file called "docs.xml" and serve up the comments within. Next, let's configure Visual Studio to generate "docs.xml". Right click your Console Application Project and click properties. Navigate to the "Build" tab and check "XML documentation file" at the bottom. Rename the file to "docs.xml" but leave the path intact.

Next we need to start the web service from Main() in program.cs:

using System;
using System.Diagnostics;
using Microsoft.Owin.Hosting;

namespace OwinSwagger
{
    class Program
    {
        static void Main( string[] args )
        {
            var url = "http://*:5000";
            var fullUrl = url.Replace( "*", "localhost" );
            using( WebApp.Start( fullUrl ) )
            {
                Console.WriteLine( "Service started at {0}", fullUrl );
                Console.WriteLine( "Press ENTER to stop." );
                LaunchDocumentation( fullUrl );
                Console.ReadLine();
            }
        }

        static void LaunchDocumentation( string url )
        {
            Process.Start( "chrome.exe", string.Format( "--incognito {0}", url + "/swagger/ui/index" ) );
        }
    }
}

When we run the app, it will launch chrome and navigate to http://localhost:5000/swagger/ui/index, which is the default location of the Swagger web page hosted by Swashbuckle. This gives the console application a nice CTRL+F5 experience. Finally, let's add a controller and a resource so we can see our generated documentation in action. Create a new class called BookController:

using System.Web.Http;
using System.Web.Http.Description;

namespace OwinSwagger
{
    /// <summary>
    /// Resource representing a book.
    /// </summary>
    public class Book
    {
        /// <summary>
        /// The self-link
        /// </summary>
        public string Href { get; set; }

        /// <summary>
        /// The name of the author
        /// </summary>
        public string Author { get; set; }

        /// <summary>
        /// The title of the book
        /// </summary>
        public string Title { get; set; }
    }

    public class BookController : ApiController
    {
        /// <summary>
        /// Retrieves a book with the specified Id.
        /// </summary>
        /// <param name="id">The id of the book to retrieve</param>
        [ResponseType( typeof( Book ) )]
        public IHttpActionResult Get( string id )
        {
            //a real controller would need to take the id and look up the book in the database
            //let's hack it below to always return a single book
            var book = new Book
            {
                Author = "Stephen King",
                Title = "Hearts in Atlantis",
                Href = Request.RequestUri.ToString(),
            };
            return Ok( book );
        }
    }
}

Start the project (CTRL + F5) and you should see the following:

Notice all the XML comments on our Book and BookController are displayed in this handy little web page. It also shows the HTTP methods that are available, descriptions and names of parameters, and even includes a "Try it out!" button to call your API right from the documentation page. Clicking the "Try it out!" button is left as an exercise for the reader.

This documentation is auto-generated and will always be up-to-date as long as your keep your comments fresh. In future posts, I will describe how to use advanced REST clients like Postman to load up the swagger specification and create an entire API preset.

Here's a link to this code on Github: https://github.com/robzhu/OwinSwagger