Generating Documentation For Web API 2.0

In my previous article, we got the gist of Web APIs, but we didn't do anything on the documentation part. So in this article, we will cover the documentation of our Web API which will help users who are 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 what the API is doing, one can easily consume these APIs. It is similar to WSDL for Web Servcies.

How to get Swagger?

Swagger is an open source library with the name SwashBuckle and can be taken by any means of importing package. Let’s have a look at how to get it from NuGet,

 

What code changes are required?

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

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 by enabling the user interface:

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 with a URL as http://localhost:3394/swagger/Version1/swagger.json. Please note, for you, it can be a different port number. Once the page is loaded, you can see the generated JSON as:

 

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

Last but not least, the UI part. To view the UI, the URL has to be changed slightly as http://localhost:3394/swagger/

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