11

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.

enter image description here

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?

4 Answers4

9

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

dthrasher
  • 40,656
  • 34
  • 113
  • 139
8

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.

enter image description here

大陸北方網友
  • 3,696
  • 3
  • 12
  • 37
  • does this path work for every scenario? e.g. publishing, deployment, ... –  Dec 15 '20 at 08:36
  • to make it work I would have to set this output path "bin\Debug\netcoreapp3.1\" so I'm not sure if this covers all the things –  Dec 15 '20 at 11:18
1

You can change project.csproj then you get the xml file at debug[desired location] folder with a custom name.I commented out the default line.

<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
    <!--<DocumentationFile>C:\Users\furkan.katman\source\repos\WebApplication1\WebApplication1\WebApplication1.xml</DocumentationFile>-->
      <DocumentationFile>bin\Debug\ProjectName.XML</DocumentationFile>
  </PropertyGroup>
katmanco
  • 1,146
  • 12
  • 24
0

As far as my investigation went, I noticed differences between $(ProjectDir), $(MSBuildProjectDirectory) or $(MSBuildThisFileDirectory) in the <DocumentationFile> element.

In the context of my solution (.NET Core 3.1), the first two both resolved to C:\ hence failing the build with a "Could not write to output file -- Access is denied" exception. Only the third keyword actually resolved to the folder path where my .csproj was located.

So I would suggest trying with MSBuildThisFileDirectory if your build fails.

T0T4R4
  • 61
  • 1
  • 3