Posts
12
Comments
163
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
Gravatar
# re: Show off your API with a little Swagger...
Ann
12/8/2017 12:52 AM
nice post
see more
Gravatar
# re: Show off your API with a little Swagger...
Dorrah
12/8/2017 5:41 AM
I have gone through the Demo API shared here and it was really helpful. The code shared here was really useful for people who are interested on this concept. Since I am new to this topic, I want to start from its beginning. Please update more details here.glass bongs online
Gravatar
# re: Show off your API with a little Swagger...
Anna Shetty
1/10/2018 3:13 AM
I really like your point you have written very amazingly. Thanks for sharing your information with everyone and keep posting. Do router login
Gravatar
# re: Show off your API with a little Swagger...
Dorrah
1/29/2018 11:15 PM
I don’t know much about coding and development but many of my friends are into it. I hope that this post about .NET shared here on the page will be useful to many programmers out there. Keep up the good work guys. print spooler service not running
Gravatar
# re: Show off your API with a little Swagger...
Sajan
2/20/2018 6:44 AM
SBI Clerk Result 2018 SBI Clerk Pre Mains Exam Result 2018 SBI Junior Associates JA Pre Mains Final Result 2018 SBI Clerk Pre mains Mains Exam Marks Cut Off Marks SBI Clerk Pre Mains Result Updates State bank Of India Clerk Ja Junior Associates Regional Wise Cut off Merit List 2018 sbi.co.in ...
State Bank of India Recruitment
How to check SBI Clerk results declared
Gravatar
# re: Show off your API with a little Swagger...
Benit
2/26/2018 1:44 AM
Whether you're a cord-cutter or simply trying to tune in while in transit, these live streams will ensure you won't miss a thing when the Oscars ceremony airs live on Feb. 26 at 7 p.m..
Gravatar
# fix your antivirus issues
mcafee activation problem
3/15/2018 5:40 AM
Before you plan to install antivirus software on your device, you are required to take
few important steps to avoid software conflicts with the previously installed versions. please visit
mcafee activation problem
Gravatar
# re: Show off your API with a little Swagger...
Vineetha
3/25/2018 10:26 AM
Watch live streams of the 2018 FIFA Men's World Cup in Russia at FOX Sports, plus highlights, schedules, standings, stats, teams, players, and more.
The United States Men's National Soccer Team returns to action on Friday in a must-win game against Honduras, a game that will live stream from San Jose, California, with the USA needing a win to keep their hopes of qualifying for the 2018 Argentina vs Iceland World Cup online channels. The Americans sit at the bottom ...
Gravatar
# re: Show off your API with a little Swagger...
roll the ball
4/10/2018 10:24 PM
Thanks for sharing.I hope you continue to have such quality articles to share with everyone! I believe there will be many people who share my views when they read this article from you.
- roll the ball

Post Comment

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