As the size of any application grows, and the number of web API endpoints grows, it is often a good idea to have documentation about the API itself, the available endpoints, what they expect as parameters, and what to expect as a normal response from any respective API calls that are made.

It can be tedious to document every API endpoint manually, but fortunately, Swagger/OpenAPI comes to the rescue here. Let's take a look:

1. Go to our Tic-Tac-Toe demo application, right-click on the TicTacToe project, go to the NuGet Package Manager, and search for Swashbuckle.AspnetCore. Now, click on the Install button: 

You can also install Swashbuckle by going to the Package Manager Console and typing Install-Package Swashbuckle.AspNetCore -Version 5.0.0-rc4 at the Package Manager's Command Prompt.

2. Next, add the following code snippet to the ConfigureServices method in the Startup class:

            services.AddSwaggerGen(options =>
            {
                options.SwaggerDoc("v1", new OpenApiInfo {
                    Title = "Learning ASP.Net Core 3.0 Rest-API",
                    Version = "v1",
                    Description = "Demonstrating auto-generated
                     API documentation",
                    Contact = new OpenApiContact
                    {
                        Name = "Kenneth Fukizi",
                        Email = "[email protected]",                       
                    },
                    License = new OpenApiLicense
                    {
                        Name = "MIT",                       
                    }
                });

3. Finally, we need to add the following code to the Configure method in the same Startup.cs class:

            app.UseSwagger();

            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", 
                 "LEARNING ASP.CORE 3.0 V1");
            });

4. Start the TicTacToe demo application and add Swagger to the root URL. You will see all the API endpoints we have created so far, all of which are documented on the Swagger index page:

5. Swagger can also be used to test out the intended functionality for any API endpoint instead of the other most common tools, such as Postman and Fiddler. Of course, another common way to test API endpoints is by typing them in manually as browser URLs. You can test an endpoint using Swagger by clicking on it (to expand it), clicking on the Try it out button, as shown to the right of the following screenshot, and entering the expected values:

6. We may want to have the API documentation on the main index page, especially in cases where the whole application is an API that we are developing for other users. In this case, all we need to do is add an empty RoutePrefix SwaggerUIOption, as follows:

            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", 
                 "LEARNING ASP.CORE 3.0 V1");
                c.RoutePrefix = string.Empty;
            });

For every additional API endpoint you wish to add, Swagger will pick it up and document it automatically, leaving you to concentrate on just producing the code and not the documentation – isn't that liberating?