Question 86822 in ASP.NET Question posted in
The official documentation can be found here.

How do I use the IncludeXmlComments to point to my second project in the same solution – Asp.net

So I have a solution with two projects, the main project being MultipleProjectsSwaggerDocs and then Public which I added as a reference to the main project. Both of these are ASP.NET Web API (.NET 6) and I have the main project as the startup project.

I’m trying to setup Swagger so that xml comments that are above the function show in the UI, for instance.
enter image description here

I’ve actually managed to get it to work by following the guide over here.
I then noticed that it wouldn’t show xml comments that I added to Public, it would only show the comments that were in theMultipleProjectsSwaggerDocs project.

So after looking around for a while, I noticed that I could just add another options.IncludeXmlComments(...) and the only problem with that is that I need to hardcode the path to the file that’s generated in the other project.

That won’t work if I were to host the project.

Here is what the Program.cs looks like for the main project MultipleProjectsSwaggerDocs

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "ToDo API",
        Description = "An ASP.NET Core Web API for managing ToDo items",
        TermsOfService = new Uri("https://example.com/terms"),
        Contact = new OpenApiContact
        {
            Name = "Example Contact",
            Url = new Uri("https://example.com/contact")
        },
        License = new OpenApiLicense
        {
            Name = "Example License",
            Url = new Uri("https://example.com/license")
        }
    });

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

    /* Issue */
    options.IncludeXmlComments(@"C:UsersHomePCsourcereposMultipleProjectsSwaggerDocsPublicbinDebugnet6.0Public.xml");
});

As of right now, that works great, it shows the docs for each endpoint.
enter image description here

But as you can see, the path to the other xml file is hardcoded, and that’s not good if I were to host the project, because it wouldn’t find the file. Is there something I can do in order to point it to the second project?

And if this is not the correct way to setup AddSwaggerGen with two projects in one solution, then what is?

Tags:

2

Answers


  1. 0

    See, it is not necessary to hardcode the full path to the second xml comments file. When you connected the first file, you wrote Path.Combine(AppContext.BaseDirectory, xmlFilename). Nobody forbids you to do the same with the second 🙂

    For example, I usually use the following code to connect my xml comments to Swagger:

    string[] allMyXmlCommentFileNames =
{
    $"{Assembly.GetExecutingAssembly().GetName().Name}.xml",
    "Public.xml"
};
foreach (string fileName in allMyXmlCommentFileNames)
{
    string xmlFilePath = Path.Combine(AppContext.BaseDirectory, fileName);
    if (File.Exists(xmlFilePath))
        options.IncludeXmlComments(xmlFilePath, includeControllerXmlComments: true);
}

    Some theory why this should work

    For example, if you open the PublicPublic.csproj file, then in my case Rider will generate the following code for me in this file if I add xml comment generation to this project:

    <DocumentationFile>binDebugnet6.0Public.xml</DocumentationFile>

    And when you build a .NET project, all projects linked to it are added as separate dlls to the binDebugnet6.0 folder of the project you are building. And it works for xml comments too, they will be there too.

    Login or Signup to reply.
  2. 0 
        builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "ToDo API",
        Description = "An ASP.NET Core Web API for managing ToDo items",
        TermsOfService = new Uri("https://example.com/terms"),
        Contact = new OpenApiContact
        {
            Name = "Example Contact",
            Url = new Uri("https://example.com/contact")
        },
        License = new OpenApiLicense
        {
            Name = "Example License",
            Url = new Uri("https://example.com/license")
        }
    });
    foreach (var filePath in System.IO.Directory.GetFiles(Path.Combine(Path.GetDirectoryName(Assembly.GetExecutingAssembly().Location)!), "*.xml"))
    {
        try
        {
            options.IncludeXmlComments(filePath);
        }
        catch (Exception e)
        {
            Console.WriteLine(e);
        }
    }


});
    Login or Signup to reply.
Please signup or login to give your own answer.

Back To Top
Search