XML comments are not shown in Swagger documentation, is this bug in swagger?

Question

The Swagger xml comments are not showing in the doc UI, not sure i am missing something here.. atleast someone direct me that this is a bug

Step1: Create a new brand new ASP.NET web application Web API project

Step2: Created a Web API Project

Step3: Installed Swashbuckle 5.6.0 NuGet packages

Step4: Enabled to generate XML documentation file (Project properties -> Build)

Step5: Updated SwaggerConfig.cs to includeXmlComments

public static void Register()
{
    var thisAssembly = typeof(SwaggerConfig).Assembly;

    GlobalConfiguration.Configuration.EnableSwagger(c =>
    {
                var xmlFile = "bin\\" + $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
                c.IncludeXmlComments(xmlPath);
     });
}

Step6: Added XML comments to the controller

///<Summary>
/// Get these comments1
///</Summary>
public class ValuesController : ApiController
{
    ///<Summary>
    /// Get these comments2
    ///</Summary>
    public IEnumerable<string> Get()
    {
        return new string[] { "value1", "value2" };
    }
}

The WebApplication1.xml is generated in the bin folder too

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>WebApplication1</name>
    </assembly>
    <members>
        <member name="T:WebApplication1.Controllers.ValuesController">
            <Summary>
             Get these comments1
            </Summary>
        </member>
        <member name="M:WebApplication1.Controllers.ValuesController.Get">
            <Summary>
             Get these comments2
            </Summary>
        </member>
        <member name="M:WebApplication1.Controllers.ValuesController.Get(System.Int32)">
            <Summary>
             Get these comments3
            </Summary>
        </member>
        <member name="M:WebApplication1.Controllers.ValuesController.Post(System.String)">
            <Summary>
             Get these comments4
            </Summary>
        </member>
        <member name="M:WebApplication1.Controllers.ValuesController.Put(System.Int32,System.String)">
            <Summary>
             Get these comments5
            </Summary>
        </member>
        <member name="M:WebApplication1.Controllers.ValuesController.Delete(System.Int32)">
            <Summary>
             Get these comments6
            </Summary>
        </member>
    </members>
</doc>

But the Swagger UI not showing comments, I am not sure where i am getting wrong here:

Put a breakpoint at the xmlPath variable and check if the path is correct — CodeNotFound, Feb 19 '21 at 22:04
The XML path is correct and i do see the XML file with comments created in the bin folder — ram4sof, Feb 19 '21 at 22:35
on the first step you are creating ASP.NET Core project, but SwaggerConfig.cs is created when you add Swashbuckle package to ASP.NET Web API. If you are using Core, use Swashbuckle.AspNetCore package — Yehor Androsov, Mar 10 '21 at 17:34
@GuilhermeWaltricke OP's issue was because of they were using ASP.NET package instead of Core — Yehor Androsov, May 31 '21 at 16:24
In my case I have .net framework 4.5.2 and added Swashbuckle.Core.Net45 and voila! — Aly González, Jun 17 '23 at 12:59
The experience in my before comment wa only luck ,the true cause was I had using MetaData Classes and Swagger get the summary of whose classes for the documentation. Excuse me! — Aly González, Jul 07 '23 at 23:54

score 29 · Answer 1 · edited Aug 23 '22 at 09:36

29

For .NET 6 make sure you configure your program.cs

builder.Services.AddSwaggerGen(c =>
{
  c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, 
  $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"));
});

Then add the property group in your .csproj

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

edited Aug 23 '22 at 09:36

StuartLC

104,537
17
209
285

answered Jun 09 '22 at 18:45

Edward Garcia

409
6
14

very good, thanks – hamaronooo Jul 17 '22 at 08:28

score 3 · Answer 2 · answered May 12 '23 at 14:48

In my case, the XML comments were missing in Swagger because the API itself and the model classes are in different assemblies.

I solved it like this:

public void ConfigureServices(IServiceCollection services)
{
    // ...

    services.AddSwaggerGen(c =>
    {
        // ...other stuff

        // include API xml documentation
        var apiAssembly = typeof(SomeApiClass).Assembly;
        c.IncludeXmlComments(GetXmlDocumentationFileFor(apiAssembly));

        // include models xml documentation
        var modelsAssembly = typeof(ModelsProject.SomeModelClass).Assembly;
        c.IncludeXmlComments(GetXmlDocumentationFileFor(modelsAssembly));
    });
}

private static string GetXmlDocumentationFileFor(Assembly assembly)
{
    var documentationFile = $"{assembly.GetName().Name}.xml";
    var path = Path.Combine(AppContext.BaseDirectory, documentationFile);

    return path;
}

Of course, don't forget to enable XML documentation in both .csproj files as well.

score 1 · Answer 3 · edited Jan 20 '22 at 08:10

Try doing

remove old
Right-click the project in Solution Explorer and select Edit <project_name>.csproj.
Manually add the highlighted lines to the .csproj file

<PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

generate new file

https://learn.microsoft.com/en-us/samples/aspnet/aspnetcore.docs/getstarted-swashbuckle-aspnetcore/?tabs=visual-studio

enter image description here

score 1 · Answer 4 · answered Sep 10 '22 at 01:07

For .NET 6 another way of doing it base on this Microsoft docs:

Opening Project file .csproj and add this lines

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

Then in Program file Change this:

  builder.Services.AddSwaggerGen();

To this

builder.Services.AddSwaggerGen(options =>
{
    // using System.Reflection;
    var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));
});

score 1 · Answer 5 · answered Jan 31 '23 at 11:32

1

In my case, the comments weren't appearing because I had put a url inside the remarks. Not sure why it broke it, but once I had removed the url everything worked.

answered Jan 31 '23 at 11:32

hooah

36
4

1

You provided the hint I needed. In my case, I included an ampersand inside the remarks, i.e. ... & ... and all my diligent documentation became invisible. – CAK2 Mar 09 '23 at 15:00

score 1 · Answer 6 · answered Mar 09 '23 at 15:01

1

Do not include any ampersands in your remarks. If you do, you documentation will not be displayed.

answered Mar 09 '23 at 15:01

CAK2

1,892
1
15
17

score 0 · Answer 7 · answered Oct 06 '22 at 17:04

At my case, I set always copy for xml generated at build option.

and at startup at AddSwaggerGen option, I add the some code, if file exist, generate comments by IncludeXmlComments :

        services.AddSwaggerGen((opt) =>
        {
            opt.SwaggerDoc("v1", new OpenApiInfo { Title = "API", Version = "v1",
                Description = "Your app desc",
                Contact = new OpenApiContact()
                {
                    Name = "@yourname",
                    Url = new System.Uri("yoursite.com"),
                }
            });

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

            if (File.Exists(xmlPath))
                opt.IncludeXmlComments(xmlPath);
        });

XML comments are not shown in Swagger documentation, is this bug in swagger?

7 Answers7

Linked