Configure Swagger UI in Web API

Swagger UI

Swagger is the largest framework for designing APIs using a common language and enabling the development across the whole API lifecycle, including documentation, design, testing, and deployment.

The framework provides a set of tools that help programmers generate client or server code and install self-generated documentation for web services.

However, there are many other frameworks like RAML, API Blueprint, Summation, etc. So, how to explain the huge popularity of Swagger? The answer is that it offers a lot of advantages and besides creating clear documentation provides other great things.

Swagger -Advantages

Ø  Swagger uses a common language that everyone can understand, it’s easily comprehensible for both developers and non-developers.

Ø  Swagger is easily adjustable, it can be successfully used for API testing and bug fixing

Ø  Swagger provides a set of great tools for designing APIs and improving the work with web services:

Ø  Generate Beautiful and Interactive Documentation

             Publish and Market your API

Different swagger tools

Ø    Swagger Editor – enables to write API documentation, design and describe new APIs, and edit the existing ones. The first open-source editor visually renders OAS/Swagger definition with error handling and real-time feedback.

Ø    Swagger Codegen – allows developers to generate client library code for different platforms. As the tool helps facilitate the dev process by generating server stubs and client SDKs, software engineers get the ability to faster build your API and better focus on its adoption.

Ø   Swagger UI – allows engineers to get self-generated documentation for different platforms. Swagger UI is a fully customizable tool that can be hosted in any environment. A great plus is that it enables developers to save a lot of time for API documentation.

Ø   Swagger Inspector – a tool for testing and auto-generating OpenAPI documentation for any API. Swagger Inspector allows to easily validate and test APIs with no limits on what you test. Tests are automatically saved in the cloud with a simple access.

Swagger UI Configuration:

Step 1: Create a web api project (Preferably you can opt template provided by Microsoft-scaffolding).

Step 2: Add swagger from Nuget package

Step 3: Check your solution you can see a SwaggerConfig.cs file inside App_Start folder.

Step 4: Open the SwaggerConfig file and uncomment below line

c.IncludeXmlComments(GetXmlCommentsPath());

Step 5: Include the method GetXmlCommentsPath in the file

 

private static string GetXmlCommentsPath()

        {

            return String.Format(@"{0}\App_Data/XmlDocument.xml", System.AppDomain.CurrentDomain.BaseDirectory);

        }

Note: There any many configuration changes you can do with swagger config look into the commented lines or swagger config or visit https://swagger.io/ for better understanding.

Step 6: Enable summary comments for the project

Uncomment below line from Areas->App_Start->HelpPageConfig.cs

config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));

Step 7: Add the summary comment xml file path in the project properties

Note: If you are using a project without scaffolding template, or if you need more idea on the help page summary comments then visit

https://docs.microsoft.com/en-us/aspnet/web-api/overview/getting-started-with-aspnet-web-api/creating-api-help-pages

Step 8: Add a link for swagger UI

Step 9: Run your project and click on the Swagger link you can see the swagger UI

Note: If you want to enable custom headers are authentication headers in the Swagger UI then you create a filter like below for doing the same

public class AddAuthorizationHeaderParameterOperationFilter : IOperationFilter

    {

        public void Apply(Swashbuckle.Swagger.Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)

        {

            if (operation.parameters != null)

            {

                operation.parameters.Add(new Parameter

                {

                    name = "Authorization",

                    @in = "header",

                    description = "access token",

                    required = false,

                    type = "string"

                });

                operation.parameters.Add(new Parameter

                {

                    name = "currentLanguage",

                    @in = "header",

                    description = "Current language",

                    required = false,

                    type = "string"

                });

            }

        }

    }

You can check the JWT reusable component (The one available in the reusable component factory) for working demo