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:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
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.
Discover more from Matt Ruma
Subscribe to get the latest posts sent to your email.