Controller summary does not appear in the api doc

[hongyiqin]

This seems like an old issue but it still exists in the latest build of Swashbuckle.

https://github.com/domaindrivendev/Swashbuckle/issues/146

XML comments on ApiController won't show up in the api doc as well as in the swagger UI

[lifei6671]

me too！！！

[another-guy]

same here

[MB34]

Wow, almost 2 YRS later and still no movement on this. How do you expect to fully document the API without being able to show what the action is for?

[domaindrivendev]

MB34 - Wow, you've obviously never put literally thousands of personal hours into a tool that you provide to the community free of charge. If you did - I don't think you'd be coming out with comments like that.

The reason this has been low on the priority list is because it's not something I've run into issues with. You can absolutely describe what every action in your API does using XML comments on your actions.

[replaysMike]

even still, I'll thumbs up this too. I'll implement this and issue a PR, since it shouldn't be difficult.

[Moritzschmidt]

Still there

[heldersepu]

Can someone please provide a link to a project to reproduce this issue...

[yue-fei]

I want to know why swashbuckle not support show 'Controller Summary'.

And I found the performance was poor under 5.3.2 version (someone has a similar problem [IncludeXmlComments]), now I'm using 5.6.0 version.

this my solution:

private void loadComments(SwaggerDocsConfig config)
{
    var basePath = AppDomain.CurrentDomain.BaseDirectory;
    var path1 = Path.Combine(basePath, "bin//demo1.XML");
    var path2 = Path.Combine(basePath, "bin//demo2.XML");

    config.IncludeXmlComments(path1);
    config.IncludeXmlComments(path2);

    var xmlDoc = XDocument.Load(path1);
    xmlDoc.Root.Add(XDocument.Load(path2).Root.Elements());

    config.GroupActionsBy(apiDesc =>
    {
        var controllerName = apiDesc.ActionDescriptor.ControllerDescriptor.ControllerName;
        var controllerFullName = apiDesc.ActionDescriptor.ControllerDescriptor.ControllerType.FullName;
        var controllerType = apiDesc.ActionDescriptor.ControllerDescriptor.ControllerType.GenericTypeArguments.FirstOrDefault()?.FullName;

        var member = xmlDoc.Root?.XPathSelectElement($"/doc/members/member[@name=\"T:{controllerType}\"]/summary") ??
            xmlDoc.Root?.XPathSelectElement($"/doc/members/member[@name=\"T:{controllerFullName}\"]/summary");

        return member == null ? $"{controllerName}" : $"{controllerName} : {member.Value}";
    });
}

[rvhuang]

The feature is still necessary as we usually will provide a general summary of what the controller can do to viewers. Also, it could be redundant if we describe same things (for example, return value conventions) in every action.

[trickshot2012]

its 2019 and thers still no progress ?

[heldersepu]

@trickshot2012 Read: https://github.com/domaindrivendev/Swashbuckle/issues/572#issuecomment-252976995

[another-guy]

@heldersepu, devs like me would definitely help resolving this real issue. Problem is how the pull requests are treated.

[heldersepu]

@another-guy There is nothing stopping you from forking the project and merging any pull request ...

Heck you could also detach your fork and rename it then deploy to nuget. That is what I did:

https://github.com/heldersepu/Swagger-Net

[domaindrivendev]

@another-guy - you should keep in mind that open source maintainers are pouring so much personal time into their projects with no financial benefit and as such, owe the community absolutely nothing.

[domaindrivendev]

With a young family, other OSS engagements (specifically the ASP.NET Core version of Swashbuckle) and the job that you know ... actually pays the bills, I don't have any time to continue maintaining this particular project.

But here's an idea - at this point, I'd be happy to make yourself and @heldersepu core contributors for this version of Swashbuckle. If you're both willing, you could address some of the open pull requests and keep the project breathing. Thoughts?

[domaindrivendev]

@heldersepu - I know we had discussed this in the past, not sure if you're still interested?

[heldersepu]

@domaindrivendev I don't know, at this point migrating what I've done on Swagger-Net will be a huge undertaking... Will reach out directly lets chat.

[another-guy]

@domaindrivendev you don't need to explain these things to me. I too have a family and a 1.5yo child, and an OSS project to contribute to, and a full-time job.

I don't think I blamed anyone here; just pointed a symptom. If the PR processing time is slow, there will be less motivation to new people to contribute. That is it.

[ghost]

Make sure your namespace is for your project and isn't something like: namespace SpaceAliensAttack { public class SwaggerConfig { ...

[Liversage]

At least in Swashbuckle version 5 there is support for /// <summary> comments on controllers. However, this is not turned on by default so seeing this issue was open led me to believe that it was not supported.

In fact you can enable it in the call to IncludeXmlComments:

services.AddSwaggerGen(c =>
{
    var xmlPath = ...;
    c.IncludeXmlComments(xmlPath, includeControllerXmlComments: true);
});

The default value of includeControllerXmlComments is false but if you use true controller XML comments will be included in the generated Swagger site.

[bingxueyinlian]

@Liversage thanks,it's work for me

[jasper-lai]

@Liversage

I have the same problem for summary not show in Swagger UI, I'm using the Swagger 5.6.0, I cannot see where to append the following code you mentioned :

services.AddSwaggerGen(c =>
{
    var xmlPath = ...;
    c.IncludeXmlComments(xmlPath, includeControllerXmlComments: true);
});

The following is some extraction of SwaggerConfig.cs ( version 5.6.0 onfig.cs ( version 5.6.0 )

GlobalConfiguration.Configuration
    .EnableSwagger(c =>
        {
            // ....

            // If you annotate Controllers and API Types with
            // Xml comments (http://msdn.microsoft.com/en-us/library/b2s063f7(v=vs.110).aspx), you can incorporate
            // those comments into the generated docs and UI. You can enable this by providing the path to one or
            // more Xml comment files.
            //
            c.IncludeXmlComments(GetXmlCommentsPath());

            //....
        }

and I have to implement GetXmlCommentsPath() method

private static Func<XPathDocument> GetXmlCommentsPath()
{
    //throw new NotImplementedException();
    return () => new XPathDocument(HostingEnvironment.MapPath(@"~/App_Data/XmlDocument.xml") ?? throw new InvalidOperationException());
}

But there is no second parameter (example: includeControllerXmlComments)

Would you help me ? Thank you.

[Liversage]

@jasper-lai I'm using Swashbuckle.AspNetCore which isn't clear from my comment. When I wrote it I probably didn't realize that this issue is in the "old" Swashbuckle repository as I found the issue by doing a web search.

I'm not familiar with the process required to enable controller XML comments in a .NET Framework Web API project.

[jasper-lai]

@Liversage Thank you for your reply. I'm still developing Web Application with ASP.NET MVC and ASP.NET MVC API. Maybe a few years later, when I'm developing with ASP.NET Core and using Swagger as API document tools, I can still refer to the way you provided.

[asadmalik3]

@Liversage Your answer works. Can i ask why this property is false by default? Are there any performance concerns here?

[Liversage]

@asadmalik3 Not being a contributor to Swaschbuckle I didn't decide why the default is false so I can't answer any "why" questions. However, it seems like a good default. Even if you have XML comments on your controllers they might not add anything useful. The documentation for OrdersController could be

The controller having actions related to orders.

This does not really provide any additional information.

And with regards to performance: Yes, there is a (very small) performance penalty to including controller documentation both in terms of CPU and memory but you only pay this penalty when the Swagger model is built which I expect should only happen once in the lifetime of the hosting process. Furthermore, I will expect that the "performance penalty" of most actions included in Swagger is greater than the "performance penalty" of including documentation for a controller and you are probably fine with including all actions in your Swagger documentation without any concerns for performance.

In other words: Using Swashbuckle, with or without controller comments, does not adversely affect the actual performance of your web site.