Generating documentation for Web API 2.0

In my previous article, we got the gist of Web API but we didn’t do anything on documentation part. So, in this article we will cover the documentation of our Wep API which will help the users using Swagger.

What is Swagger?

Swagger is a standard which is used to define the API, so that endpoints can be found and discovered easily with the help of small documentation along with the user interface. If it is clear that what API is doing, one can easily consume these APIs. It is similar to WSDL for Web Services.

How to get Swagger?

Swagger is an open source library with a name SwashBuckle and can be taken by any means of importing packages. Let’s have a look on how to get it from Nuget:

What code changes are required?

First of all, we have to go and register the service for swagger as:

public void ConfigureServices(IServiceCollection services)
{
services.AddMvc();
services.AddSwaggerGen(options=> 
{

options.SwaggerDoc("Version 1", new Swashbuckle.AspNetCore.Swagger.Info
{ Title = "Conference Planner", Description = "This holds methods
to perform CRUD operation using in-memory database." });

});

services.AddDbContext<ApplicationDbContext>(context => {
                 context.UseInMemoryDatabase("ConferencePlanner"); });
        }       

Next, we must do configuration related changes along with enabling the user interface for us. This can be done as:

       

public void Configure(IApplicationBuilder app, IHostingEnvironment env)


{

if (env.IsDevelopment())

{  app.UseDeveloperExceptionPage();

            }


app.UseSwagger();

app.UseSwaggerUI(swag =>

{

swag.SwaggerEndpoint("/swagger/version1/swagger.json", "Conference Planner APIs");


            });

        app.UseMvc();
}    

We are almost there. Now quickly build and run the application. Please note, for you it can be different port number. Once the page is loaded, you can see the generated JSON as:

Above JSON contains all the information which is required for any consumer.

Last but not the least, the UI part. To view the UI, URL has to be changed slightly as we need to append /swagger at the end.

And we are done with SwashBuckle, which is an implementation of Swagger. Happy learning.