CODEWITHSUNDEEP
asp.net-coreswaggerswagger-2.0
ram4sof
ram4sof

Reputation: 465

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

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

enter image description here

Step2: Created a Web API Project

enter image description here

Step3: Installed Swashbuckle 5.6.0 NuGet packages

enter image description here

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

enter image description here

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: enter image description here

Upvotes: 15

Views: 18580

Answers (8)

Edward Garcia
Edward Garcia

Reputation: 594

For .NET 6 (or later) 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>

Upvotes: 45

Sanskar7_8
Sanskar7_8

Reputation: 7

I also faced this issue for getting XML comments for controllers in the swagger page UI in .net6 core. I found a simple solution by enabling the "XML Documentation file path" option in the properties of the project. you can follow below mentioned simple steps:

  • Add the functionality while configuring thr swagger in program.cs or startup.cs

    builder.Services.AddSwaggerGen (c => { c.SwaggerDoc("v1", new OpenApiInfo { Title = "JWTToken_Auth_API", Version = "v1" }); c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, $"{Assembly.GetExecutingAssembly().GetName().Name}.xml")); });

  • Right-click on the project and open the properties.

  • Go to Build -> Output -> Enable "Documentation file". (Also, you can set your path for XML documentation file or the default location will be used) enter image description here

Upvotes: 0

HyperQuantum
HyperQuantum

Reputation: 1672

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.

Upvotes: 7

CAK2
CAK2

Reputation: 1990

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

Upvotes: 1

hooah
hooah

Reputation: 76

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.

Upvotes: 1

toha
toha

Reputation: 5510

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);
        });

Upvotes: 0

Okyam
Okyam

Reputation: 730

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));
});

Upvotes: 1

kawtog
kawtog

Reputation: 11

Try doing

  1. remove old
  2. Right-click the project in Solution Explorer and select Edit <project_name>.csproj.
  3. Manually add the highlighted lines to the .csproj file
<PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
  1. generate new file

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

enter image description here

Upvotes: 1

Related Questions