Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

IncludeXmlCommentsFromInheritDocs is broken in Swashbuckle.AspNetCore 6.8.0 #38

Closed
alser opened this issue Sep 25, 2024 · 10 comments
Closed

Comments

@alser
Copy link

alser commented Sep 25, 2024

// 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
Copy link

sprudel79 commented Sep 25, 2024

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
Copy link
Author

alser commented Sep 25, 2024

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
Copy link
Author

alser commented Sep 25, 2024

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

@ryankelley
Copy link

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
Copy link
Author

alser commented Oct 17, 2024

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
Copy link

Ixonal commented Dec 17, 2024

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
Copy link

sprudel79 commented Dec 17, 2024

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
Copy link
Author

alser commented Dec 17, 2024

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
Copy link

jerone commented Dec 17, 2024

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

@unchase
Copy link
Owner

unchase commented Dec 17, 2024

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

6 participants