Posts
12
Comments
79
Trackbacks
0
Show off your API with a little Swagger...

So you've built yourself a ground-breaking RESTful .NET Web Api that's effectively going to change the world... awesome!

You've even sold and marketed the idea to maybe your boss or potential client... fantastic!

And then they ask you for documentation... oops!

You're not alone, developers are notorious for "saving the world" with their code and yet always seem to overlook the obvious. But fear not!

There are a few easy solutions that you can implement that will actually do all the documentation work for you. Microsoft has their own built-in version of this, however I'm going to focus today on a specification called "Swagger."  More specifically, the implementation technology we'll be using to generate the Swagger documentation with the Web Api framework is called "Swashbuckle."

Why Swashbuckle?

Well not only does Swashbuckle allow you to have very nicely formatted documentation, it will also handle auto-generating interactive test cases for you so your consumers can easily play around with your Api while they're familiarizing themselves with it's overall usage.

Here's a couple screenshots of our Demo API found here: http://www.holisticstg.com




Here is an example of one of those interactive test cases I mentioned earlier...





"Ok, I'm sold. How do I set this up for my Web Api?"

There is actually just a few simple steps to get this up and running...

  • Open NuGet package manager within Visual Studio and install "Swashbuckle.Net45"


  • After the NuGet package is installed, you'll notice a new file has been added to your "App_Start" folder called "SwaggerConfig.cs" This file allows you to customize various aspects of your generated Swagger documentation, we'll dive more into that in a just a bit.
  • For now, you can simply use your browser and point to the root url of your api and append it with "/swagger"

So here is my controller code for our Demo API:

/// <summary>
/// Holistics Technology Group Demo API
/// </summary>
public class DemoApiController : ApiController
{
    /// <summary>
    /// Simple string example
    /// </summary>
    /// <returns>string</returns>
    [HttpGet]
    [Route("api/demoapi/helloworld")]
    public async Task<string> StringExample()
    {
        return await Task.Factory.StartNew(() => "Hello from Holistics Technology Group!");
    }

    /// <summary>
    /// Get weather summary
    /// </summary>
    /// <param name="zipCode">zip code</param>
    /// <returns>string</returns>
    [HttpPost]
    [Route("api/demoapi/todaysweather")]
    public async Task<string> Summary(string zipCode)
    {
        return await Task.Factory.StartNew(() => zipCode.LookupWeather().TodaySummary);
    }

    /// <summary>
    /// Get weather forecast object
    /// </summary>
    /// <param name="zipCode">zip code</param>
    /// <returns>WeatherData</returns>
    [HttpPost]
    [Route("api/demoapi/threedayforecast")]
    [ResponseType(typeof(WeatherData))]
    public async Task<WeatherData> Forecast(string zipCode)
    {
        return await Task.Factory.StartNew(() => zipCode.LookupWeather());
    }
}

Now that we have Swashbuckle wired up properly, we'll want to configure it to read in our XML code comments. This is where the SwaggerConfig.cs file comes into play. But first we'll need to tell Visual Studio to actually save our XML comments into our bin directory.


Then open up SwaggerConfig.cs and un-comment the line that contains "c.IncludeXmlComments" and supply the path your actual XML file name you set just above.


Swashbuckle is very configurable and we have only scratched the surface of what it can do, but this should be enough to get you up and running.

You can find out more information at the Swashbuckle GitHub site.


posted on Wednesday, June 14, 2017 2:36 PM Print
Comments
Gravatar
# re: Show off your API with a little Swagger...
CarterU
6/15/2017 12:27 PM
Awesome site!
Gravatar
# re: Show off your API with a little Swagger...
Kyle Corver
6/15/2017 12:31 PM
Awesome job and very informative post. Here, at essaypa we salute you.
Gravatar
# re: Show off your API with a little Swagger...
Temil
6/15/2017 3:49 PM
This is great article. Thanks for sharing!!! If you are on the road to document your existing api or take a design first approach, swaggerhub is a great resource.
Gravatar
# re: Show off your API with a little Swagger...
aingeru
6/23/2017 11:01 PM
Swashbuckle is configurable. It handles auto-generating interactive test cases. This might be helpful as well 192.168 ll
Gravatar
# re: Show off your API with a little Swagger...
Berra19775@gmail.com
7/25/2017 4:58 AM
I study your articles every day. And to me, they're useful. I was assisted by the article about theme at-most. I know a website CheapPaperWriters.com With answers on interesting issue.
Gravatar
# re: Show off your API with a little Swagger...
Hickley
7/26/2017 4:32 AM
I really liked the article about theme which supports the very essential subject to-day. The article on this assisted me to write an essay. But ordinary I acquire it here https://personalessaywriter.com/typical-process-of-essay-writing-on-gender-roles/
Gravatar
# re: Show off your API with a little Swagger...
Smullen
7/26/2017 4:33 AM
I lately wrote an essay and also this article relating to this topic contributed me to the results that are great results like https://personalessaywriter.com/movie-review/ I would really like to read more such posts.
Gravatar
# re: Show off your API with a little Swagger...
Stribling
7/26/2017 4:40 AM
Several times ago I bought an essay about this. If it was seen by me before I would write the essay Custompaperswriter.com by myself.
Gravatar
# re: Show off your API with a little Swagger...
A Ryan
9/2/2017 6:28 PM
Great article, thanks!Andyr
Gravatar
# re: Show off your API with a little Swagger...
animal jam
9/15/2017 10:41 PM
The article you have shared here very good. This is really interesting information for me. Thanks for sharing!
http://192168ll.tips/
Gravatar
# re: Show off your API with a little Swagger...
animal jam
9/18/2017 10:39 PM
The article you have shared here very good. This is really interesting information for me. Thanks for sharing!
192.168.1.1 login
Gravatar
# re: Show off your API with a little Swagger...
Stan
10/12/2017 12:10 AM
"Ok, I'm sold. How do I set this up for my Web Api?" Hi.
geometry dash 2.0

Post Comment

Title *
Name *
Email
Comment *  
Verification
Coding strategies for the Java and .Net developer...