ASP.NET Boilerplate: an alternative guide to integrate Swagger

Swagger is an excellent tool for API exploration of our RESTful APIs. In this post, we'll cover how to integrate and setup Swagger in an  ASP.NET Boilerplate (ABP) application (with ASP.NET MVC 5.x framework), to provide client-side documentation of its ABP application services. Most of all, this is an alternative documentation to the proposed in its official web site.

Once Swagger is ready, you can get documentation about your API at http://localhost:6634/swagger.

This guide will take a the project WebApiServerDemo as sample and it can be downloades at https://github.com/gezanoletti/WebApiServerDemo.git.

Step 1. Install dependencies

Install Swashbuckle.Core on your Web project. We recommend version 5.5.3, the current version at now.

Install Swashbuckle.Core.Extension on your Web project. Remark: I recommend you install version 1.0.0 because I have found errors with superior verions.

Step 2. Set up Swagger

Set up Swagger in your Web project module. The following is the basic configuration.

public class WebApiServerDemoWebModule : AbpModule
    {
        public override void PreInitialize()
        {
            //...
            ConfigureSwaggerUi();
        }        

        public override void Initialize() {...}

        private void ConfigureSwaggerUi()
        {
            Configuration.Modules.AbpWebApi().HttpConfiguration
                .EnableSwagger(c =>
                {
                    c.SingleApiVersion("v1", "WebApiServerDemo.WebApi");
                    c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());
                })
                .EnableSwaggerUi(c =>
                {
                    c.InjectJavaScript(typeof(WebApiServerDemoWebModule).Assembly, "WebApiServerDemo.Web.Api.Scripts.Swagger-Custom.js");
                });
        }
    }

Notice that a javascript file named Swagger-Custom.js is being injected. This file must be located in your Web project. For example:

Notice once again that filename (WebApiServerDemo.Web.Api.Scripts.Swagger-Custom.js) correspond with file path.

After that, the file Swagger-Custom.js must be settled as embedded resource and must be included in the AssemblyInfo.cs at your Web project.

//...
[assembly: WebResource("WebApiServerDemo.Web.Api.Scripts.Swagger-Custom.js", "application/x-javascript")]

And that's all! You can now explore your awesome API!

Optional references

• https://www.aspnetboilerplate.com/Pages/Documents/Swagger-UI-Integration#aspnet-5x
• https://www.codeproject.com/Articles/1078249/RESTful-Web-API-Help-Documentation-using-Swagger-U
• https://msdn.microsoft.com/en-us/library/bb398930.aspx
• https://support.microsoft.com/en-us/help/910445/how-to-embed-resources-in-asp.net-2.0-assemblies
• http://www.4guysfromrolla.com/articles/080906-1.aspx

Further Readings

Look at Swagger Code Generator for client-side code generation from your API.