in swaggerui api webapi .net ~ read.
How to setup Swagger UI - WEB API

How to setup Swagger UI - WEB API

Recently I was working on designing and developing a small scale application with RESTful API using ASP.NET WebAPI. The scalability of this project would be extended to include a large number of endpoints (depending on the features implemented) with different data models and implementation.

As the application grows, it would be feasible to have some sort of visualization of the implemented API which would help in testing and documenting the API. It is crucial to have an API that is friendly to work with and easily describe it purpose, an interesting slides by @earth2marsh and @landlessness explaining why Your API Sucks.

Swagger UI to the rescue

Swagger UI is an open source project that have a better representation of developed RESTful
API. Swagger is attempting to standardize an interface to REST APIs which allows both human and computers to discover and understand the capabilities of the service without access to source code, documentation or network traffic. Swagger follows the formal specification surrounded by a large ecosystem of tools, i.e. Microsoft, PayPal, APIGEE, etc...

Swagger UI example

Setups

Since Swagger UI is a language-agnostic which means that there are different implementation for different platforms. In the world of ASP.NET WEB API there is a simplified way to add Swagger to any WEB API application through the use of Swashbuckle.

Step 1: Install Swashbuckle

Open your Nuget Package Manager Console and enter the following:

Install-Package Swashbuckle  

Once Swashbuckle package is installed, it will install SwaggerConfig.cs in the App_Start folder, which uses WebActivatorEx to register and startup when web application is started.

"Now you can browse to your Swagger UI http://localhost:9999/swagger/"

"Depend how you run your application, I'm using IIS Express"

Initial setup of Swagger UI

Step 2:

Now, how about API documentation?

  1. Go to your project Properties

  2. On the left tabs, Select Build

  3. On Output, check "XML documentation file:"

  4. Then Save
    XML Documentation

We need to update SwaggerConfig.cs with the following

public class SwaggerConfig  
    {
        public static void Register()
        {
            var thisAssembly = typeof(SwaggerConfig).Assembly;

            GlobalConfiguration.Configuration 
                .EnableSwagger(c =>
                    {
                        c.SingleApiVersion("v1", "SwaggerUI");
                        c.IncludeXmlComments(GetAPIDocumentations());
                    }).EnableSwaggerUi(c => { });
        }
        protected static string GetAPIDocumentations()
        {
            return System.String.Format(@"{0}\bin\SwaggerUI.Owin.XML", System.AppDomain.CurrentDomain.BaseDirectory);
        }
    }

Step 3

We need to start annotating our API so that it can be visible when browsing to our Swagger page which contains a list of API calls.

This an image of how I documented my API.

API annotations

And that how it looks like in Swagger UI.

The Ghost Logo

Finally

With Swashbuckle Swagger UI can be added seamlessly to any Web API projects. It gives you the ability discover, document and experiment with your implemented API.

Please click here for the demo project.

Hopefully this post would be useful to anyone who want to documents and experiments with their Web API.

comments powered by Disqus