XML comments file could not be found - Swagger

Question

This is certainly one of those that drives you nuts. As the title indicates all I\'m simply trying to do is display comments pulled from an xml file using swagger.

I

Answer 1

in .net core 3.0

<GenerateDocumentationFile>true</GenerateDocumentationFile>

in PropertyGroup tag of .csproj file

Answer 2

Using .Net Core 2, here's the lines I needed:

var pathIncludeXmlComments = $@"{env.ContentRootPath}\Events.xml";

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new Info { Title = "Events API", Version = "v0.1" });
    c.OperationFilter<AuthorizationHeaderParameterOperationFilter>();
    c.IncludeXmlComments(pathIncludeXmlComments);
});

If you're having problems, put a breakpoint after that first line, check the value of "pathIncludeXmlComments", and confirm that VS2017 has stored an .xml file there.

And remember that under Project Properties, in the "Build" tab, you need to tick the "XML documentation file" box, and set the name to the same as shown in the filename above (Events.xml, in this example).

Answer 3

I just wanted to put an answer to this question to further explain why those codes didn't work for Tez (and didn't work for me either).

The code in question is:

var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);

For this to work, your swagger documentation configuration must be written in the "startup.cs" or in a .cs file within the same project as the controller.

Also, you must ensure that your XML file is being generated. So, right-click on your project, go to properties, go to build, scroll down to the "output" section, and check the "XML documentation file" option. (These steps are for Visual Studio 2019).

XML files are usually named "your-project-name".xml by default.

$"{Assembly.GetExecutingAssembly().GetName().Name}.xml"

Thus, this line of code ensures that the name of the xml file in your swagger configuration will be: "your-project-name".xml, where your controller documentation sits.

In my case, I had my swagger configuration in an extension method in class library, so that line of code produced the xml file name: "class-library-project-name".xml, when it should have been "controller-resident-project-name".xml.

The solution, like Tez suggested, is to manually set the XML file name, since you already know what it is.

Another solution would be to configure swagger in the startup.cs, which is usually in the same project as your controllers.

Hope this helps.

Answer 4

Make sure that the project properties in the XML Generate configuration match the XML name of your swagger configuration file. Follow print's to facilitate understanding

Project Properties

swagger configuration

Answer 5

Ok, So I managed to get it to work by pointing to the root directory.

I still have no idea why it cannot detect the xml file in the bin directory. Again this worked by adding an xml file within the root.

Code Changes:

var baseDirectory = AppDomain.CurrentDomain.BaseDirectory;
                        //var commentsFileName = Assembly.GetExecutingAssembly().GetName().Name + ".XML";
                        var commentsFileName = "Comments" + ".XML";
                        var commentsFile = Path.Combine(baseDirectory, commentsFileName);

                        c.IncludeXmlComments(commentsFile);

Answer 6

As indicated by the exception, the application looks for the XML in the base directory of the project, not in the "bin" folder.

Why does the app search in the base directory? Look at these lines:

var baseDirectory = AppDomain.CurrentDomain.BaseDirectory;
var commentsFileName = Assembly.GetExecutingAssembly().GetName().Name + ".XML";//"G2F.Collective.Api.XML"
var commentsFile = Path.Combine(baseDirectory, commentsFileName);

The name of the comment file is configured with the combination of the base directory and the xml with the name of the project

c.IncludeXmlComments(commentsFile);

Finally, this instruction tells Swagger which file to use to take the comments, it is the real reason why it looks for that file in that directory.

So what is indicated in this last instruction must be according to what is configured in the Build tab of the project configuration.