Upgrading Swagger to 5.2.X for Web API with Owin

• Download source - 10.7 KB

Introduction

There are a large number of articles and samples available on how to make Swagger 4.X version work with Web API having Owin Statup class. However, I had to do Googling and R&D to make my Web API having oWin Startup class for Swagger version 5.X.

This tip would help you upgrade Swagger package 4.1.x of your Web API application to 5.2.x. It lists the issues and resolution for common problems and would save your time.

Background

I had to deploy my Web API application with Owin Startup class in Azure as API App. When I started publishing, it automatically upgraded the Swashbuckle package to version 5.2.1 from the existing 4.1.0 version. However, the application got successfully published as Azure API App, however I could get the Swagger UI and documentation.

Using the Code

Earlier Application Settings and code (Swagger version 4.1.0)

NuGet Packages installed:

<package id="Swashbuckle"
version="4.1.0" targetFramework="net451" />
<package id="Swashbuckle.Core"
version="4.1.0" targetFramework="net451" />

Code in SwaggerConfig.cs file:

public class SwaggerConfig
{  
        public static void Register()
        {
              Swashbuckle.Bootstrapper.Init(GlobalConfiguration.Configuration);
              SwaggerSpecConfig.Customize(c =>{c.IncludeXmlComments(GetXmlCommentsPath());});
        }

       protected static string GetXmlCommentsPath()
       {
            return System.String.Format(@"{0}\bin\ApplicationName.XML", 
			System.AppDomain.CurrentDomain.BaseDirectory);
       }
}

Code in Startup.cs file:

public class Startup
{
       public void Configuration(IAppBuilder app)
      {
        //I am just giving the code that is required for Swagger initialization. 
	//Your startup class would have additional code for Cors and other initializations.
 
           HttpConfiguration config = new HttpConfiguration();
           WebApiConfig.Register(config);
       
          //Swagger
            Swashbuckle.Bootstrapper.Init(config);
            app.UseWebApi(config);
      }
}

Steps for Upgrade

1. Uninstall the below packages:
   • <package id="Swashbuckle" version="4.1.0" targetFramework="net451" />
   • <package id="Swashbuckle.Core" version="4.1.0" targetFramework="net451" />
2. Install NuGet Package
   • <package id="Swashbuckle.Core" version="5.2.1" targetFramework="net451" />
3. Delete the SwaggerConfig.cs file
4. Update the public void Configuration(IAppBuilder app) method in Startup.cs class to have the below code:

   public void Configuration(IAppBuilder app)
   {
               HttpConfiguration config = new HttpConfiguration();
               WebApiConfig.Register(config);
               config.EnableSwagger(c =>
               {
                   c.SingleApiVersion("v1", "WebAPI");
                   c.IncludeXmlComments(GetXmlCommentsPath());
               }).EnableSwaggerUi();
   
               app.UseWebApi(config);
   }

5. Add GetXmlCommentsPath method in Startup.cs class to have the below code:

   protected static string GetXmlCommentsPath()
   {
       return System.String.Format(@"{0}\bin\ApplicationName.XML", 
   			System.AppDomain.CurrentDomain.BaseDirectory);
   }

6. Build and run the applications and navigate to http://localhost:XXXX/swagger/ui/index. Please note with Swagger version 4.X, the URL was http:// localhost:XXXX/swagger/ui/index.html. You don’t need the HTML file extension in URL for Swagger version 5.X.
7. If any of your controllers have more than one Get methods, you would get the below exception:

   {"Message":"An error has occurred.",
   "ExceptionMessage":"Not supported by Swagger 2.0: 
   Multiple operations with path 'api/controlername' and method 'GET'.

8. Update the public void Configuration(IAppBuilder app) method to have the below code:

   public void Configuration(IAppBuilder app)
   {
               HttpConfiguration config = new HttpConfiguration();
               WebApiConfig.Register(config);
               config.EnableSwagger(c =>
               {
                   c.SingleApiVersion("v1", "WebAPI");
                   c.IncludeXmlComments(GetXmlCommentsPath());
                   c.ResolveConflictingActions(x => x.First());
   
               }).EnableSwaggerUi();
   
               app.UseWebApi(config);
   }

9. Run your application and navigate to http://localhost:xxxx/swagger/ui/index. You should be all set.

Points of Interest

1. To use Swagger 5.2.x with oWin StartUp class, you only need Swashbuckle.Core nuget package.
2. You have to include the XML comments explicitly from the XML file.
3. By default, Swagger would not let you have multiple methods of the same type (for example, 2 httpget methods in Accounts Controller). You need to use ResolveConflictingActions configuration.
4. There is change in the Swagger URL. The version 5.x does not require HTML extension for the index.

History

• 2^nd October, 2015: Initial version