Adventures with Azure: Swagger and XML Comments

For my API projects I like to generate XML comments that are used in conjunction with Swagger to provide better guidance on how to use the API, from methods to models.

To do this, I just add the following snippet of code to my Startup.cs file:

services.AddSwaggerGen(c => 
    {
         c.SwaggerDoc("v1",
              new Info
              {
                   Title = "Welcome to My REST API",
                   Version = $"v1",
                   Description = "We're glad you're here, and we hope you'll find the documentation helpful.",
                   Contact = new Contact
                   {
                        Name = "My Name",
                        Email = "myemail@mydomain.com"
                   }
              });

         var baseDirectory = AppDomain.CurrentDomain.BaseDirectory;

         c.IncludeXmlComments(Path.Combine(baseDirectory, "MyProject.WebApi.xml"));
         c.IncludeXmlComments(Path.Combine(baseDirectory, "MyProject.Domain.xml"));

         c.EnableAnnotations();
    });

In the above example I want to include XML comments for both my Business Domain layer and WebApi layer.

Then in each of my projects I set XML documentation file to checked.

This will include my XML documents in my Swagger documentation.

When I run it locally, it works great!

But when I push it to Azure, the site generates an error.

Digging a little deeper, I discovered that a FileNotFoundException was being thrown for both my XML files.

Taking a close look at the project settings, I saw what the issue was, when the project was built it was NOT generating the XML files to a relative path, but rather to my computer’s path.

After searching around I finally figured out that I needed to modify my .csproj file to look like the below:

This would now generate the XML files based on a relative path for both DEBUG and RELEASE.

Once I made this change and redeployed, life was good again.