Enable Swagger for Sitecore MVP Site

Recently, I saw swagger enabled for API documentation in a Sitecore project. I wanted to enable Swagger hands-on in a project of my choice so, I chose the Sitecore MVP project. I used this wonderful article as reference but ran into few issues. Hence this blog post!

Key takeaways:

1. App_Config folder is case-sensitive

2. For Swagger, enable *.Swagger.IdentityServer.config to bypass id server

3. In case of MVP site, ensure you follow correct csproj definition based on _build\props

First, a diagram representing how the Sitecore patch for Swagger works:

Now, covering my step-by-step approach here for Sitecore MVP project Swagger implementation:

1. Create a Mvp.Feature.Swagger.Platform.csproj file that looks like this:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>

    <TargetFramework>net48</TargetFramework>

    <RootNamespace>Mvp.Feature.Swagger</RootNamespace>

    <AssemblyName>Mvp.Feature.Swagger</AssemblyName>

    <SitecoreRoleType>platform</SitecoreRoleType>

  </PropertyGroup>

  <ItemGroup>

    <ProjectCapability Include="SupportsSystemWeb" />

  </ItemGroup>

  <ItemGroup>

    <PackageReference Include="Sitecore.Kernel" />

    <PackageReference Include="Sitecore.LayoutService" />   

  </ItemGroup> 

</Project>

Note that the following Directory.Build.Props expects certain properties in the file and so, the csproj file must be in above format.

So, if you add the Visual Studio .net framework class library project, that won't work in case of MVP project.

Properties for different projects can be found here: _build\props

2. Install SwashBuckle:

Note that the version needs to be added to packages.props file since by default it gets added to the csproj file:

Clean and build Mvp.Feature.Swagger project to see the error go.

3. The next issue is:

"HttpConfiguration does not contain a definition for enableSwagger":

Add the Microsoft.Aspnet.WebApi.Owin package:

4. The Microsoft.Aspnet.WebApi.Owin package adds the following namespaces and the SwashBuckle.Application namespace especially is what enableSwagger method needs:

In case of Microsoft.Aspnet.WebApi.Owin package too, ensure to update the packages.props file with the version details and remove what gets added to the csproj through nuget package manager.

5. I then shamelessly lifted all code from this github repo and replaced Pintle with Mvp.Feature.Swagger just to see what happens.

6. I spent quite sometime to find the cause for why my new config file wasn't getting deployed since container view wasn't reflecting my swagger config files under the feature folder:

Then realized that App_config is case-sensitive and must read App_Config else, the config file won't be deployed to the container.

7. My Swagger project lifted from this wonderful pintle github repo:

8. Another issue I faced is, if I don't add the Feature.Swagger.IdentityServer.config, the <cm server>/swagger url was not authenticated and popped the login page time and again. Actually, the url must be by-passed by the id server since we already have a auth handler in the pipeline and that is what this config does:

<?xml version="1.0" encoding="utf-8" ?>

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">

<sitecore>

<pipelines>

<owin.cookieAuthentication.validateIdentity>

<processor type="Sitecore.Owin.Authentication.Pipelines.CookieAuthentication.ValidateIdentity.ValidateSiteNeutralPaths, Sitecore.Owin.Authentication">

<siteNeutralPaths hint="list">

<path hint="swagger">/swagger</path>

</siteNeutralPaths>

</processor>

</owin.cookieAuthentication.validateIdentity>

</pipelines>

</sitecore>

</configuration>

9. Swagger in action finally: