Specify deployment path for XML documentation output path

Question

I'm using the Swashbuckle.AspNetCore package for my .NET Core web api project. I want to add XML comments support so I have to set Build => Output => XML documentation file to true in the application settings.

Unfortunately the autogenerated path is absolute

C:\Users\myUser\...\repository\solution\project\project.xml

So this only works on my machine. Is there a way to use placeholders? E.g.

{{pathToProject}}\project.xml

so it works while debugging locally and for the deployment?

Answer 1

There's an easy way to generate an XML documentation file at a relative path. Just set the DocumentationFile property to true:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

This was documented in another StackOverflow answer here: https://stackoverflow.com/a/47118584/19112

You can then set your SwaggerGenOptions to consume your XML documentation like this:

// Set the comments path for the Swagger JSON and UI.
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
options.IncludeXmlComments(xmlPath);

As shown in the sample here: https://code-maze.com/swagger-ui-asp-net-core-web-api/#ExtendingDocumentation

Answer 2

Click the Browse... button and select a folder under the project path, such as bin\debug.

Then check the XML documentation file. It will generate a relative path.