IncludeXmlCommentsFromInheritDocs is broken in Swashbuckle.AspNetCore 6.8.0

[alser]

// xml comments file generated by c# compiler, no matter the contents (with or w/o inheritdocs)
const string xmlFilePath = "path/to/MyAssembly.xml";

services.AddSwaggerGen(options =>
{
    options.IncludeXmlComments(xmlFilePath);
    options.IncludeXmlCommentsFromInheritDocs();
});

Call to IncludeXmlCommentsFromInheritDocs fails with the exception below.

System.ArgumentNullException: Value cannot be null. (Parameter 'source')
   at System.Linq.ThrowHelper.ThrowArgumentNullException(ExceptionArgument argument)
   at System.Linq.Enumerable.TryGetSingle[TSource](IEnumerable`1 source, Boolean& found)
   at System.Linq.Enumerable.Single[TSource](IEnumerable`1 source)
   at Unchase.Swashbuckle.AspNetCore.Extensions.Extensions.SwaggerGenOptionsExtensions.<>c.<IncludeXmlCommentsFromInheritDocs>b__7_1(FilterDescriptor x)
   at System.Linq.Enumerable.WhereSelectListIterator`2.MoveNext()
   at System.Linq.Enumerable.CastIterator[TResult](IEnumerable source)+MoveNext()
   at System.Collections.Generic.List`1..ctor(IEnumerable`1 collection)
   at System.Linq.Enumerable.ToList[TSource](IEnumerable`1 source)
   at Unchase.Swashbuckle.AspNetCore.Extensions.Extensions.SwaggerGenOptionsExtensions.IncludeXmlCommentsFromInheritDocs(SwaggerGenOptions swaggerGenOptions, Boolean includeRemarks, Type[] excludedTypes)

Same behavior if supplied XPathDocument:

options.IncludeXmlComments(() => new XPathDocument(new StringReader(File.ReadAllText(xmlFilePath))));

---

In Swashbuckle.AspNetCore sources method IncludeXmlComments results in calling to:

swaggerGenOptions.AddSchemaFilterInstance(new XmlCommentsSchemaFilter(xmlDocMembers));

which in turn does this:

swaggerGenOptions.SchemaFilterDescriptors.Add(new FilterDescriptor
{
    Type = typeof(TFilter),
    FilterInstance = filterInstance
});

therefore creating FilterDescriptor with Arguments = null.

Method IncludeXmlCommentsFromInheritDocs in this repo starts with:

var documents = swaggerGenOptions.SchemaFilterDescriptors.Where(x => x.Type == typeof(XmlCommentsSchemaFilter))
    .Select(x => x.Arguments.Single())
    .Cast<XPathDocument>()
    .ToList();

expecting to see single argument of type XPathDocument, but throwing ANE

[sprudel79]

Same issue on my side in this call of method IncludeXmlCommentsFromInheritDocs:

List<XPathDocument> list = (from x in swaggerGenOptions.SchemaFilterDescriptors
                                    where x.Type == typeof(XmlCommentsSchemaFilter)
                                    select x.Arguments.Single()).Cast<XPathDocument>().ToList();

It's working with Swashbuckle 6.7.3, the question of course is, if it's a bug in that library or my bad understanding of the required setup. I have compared the swaggerGenOptions.SchemaFilterDescriptors content when using the 6.7.3 version and for the types XmlCommentsSchemaFilter I can always see a populated Arguments property.

[alser]

It's working in Swashbuckle 6.7.3 for me too, and same code in my app was working since at least 6.5.0 with the same version of Unchase.Swashbuckle.AspNetCore.Extensions 2.7.1

[alser]

I've reported this issue to Swashbuckle repo, to see if it's intended or not from their side https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/3081

[ryankelley]

Same for my side, it looks like the change will be needed in this extension project to be compatible with Swashbuckle 6.8.0 and above

[alser]

I've fixed it in the PR linked above, not ideal fix but it works. Got no reaction from the author so far. Also it looks like CI is broken, it searches for dll to build nupkg in wrong location.

[Ixonal]

Given what @alser said and the last commit seemingly from 2 years ago, I have to ask... is this project even still active? Wondering if I should actually wait or just try to find some alternative.

[sprudel79]

Given what @alser said and the last commit seemingly from 2 years ago, I have to ask... is this project even still active? Wondering if I should actually wait or just try to find some alternative.

Indeed I didn't want to wait longer and unfortunately I had to remove the dependencies to this project in my solution. In any case, many thanks for the maintainers for all their efforts!

[alser]

Yeah, I feel the same. I've used the code from this project in my project (with the fix from the PR above), refactored it, added nullability annotations and newer C# syntax, targeting .NET 6.0+ only (got rid of legacy stuff), corrected some typos, no other changes. It works fine with the newest Swashbuckle package.

If anyone's interested, I can incorporate it back to the solution structure, push it to my fork, so that someone else can fork it, fix CI (or get a new one), do any other changes, publish new package and maintain it.

And huge thanks to the authors of this library! 😊 It has lots of features the original Swashbuckle one should have out of the box imho

[jerone]

@unchase We are kinda stuck here. Care to help us out?

[unchase]

I apologize for being away for a long time. I uploaded a fix that should solve the problem.