unchase / Unchase.Swashbuckle.AspNetCore.Extensions

:hammer: A library contains a bunch of extensions (filters) for Swashbuckle.AspNetCore.
https://www.nuget.org/packages/Unchase.Swashbuckle.AspNetCore.Extensions
Apache License 2.0
115 stars 16 forks source link

Are these the limitations of IncludeXmlCommentsFromInheritDocs? #24

Closed alekdavisintel closed 1 year ago

alekdavisintel commented 2 years ago

I wanted to post this under the discussions, but the submit button was grayed out.

I'm not sure if there is something I'm not doing right, but it looks like IncludeXmlCommentsFromInheritDocs is intended only to support two elements (summary and remarks) of inherited objects. I am trying to use <inheritdoc> pointing to a sibling method in the same class and I do not get any documentation for the controller method that uses <inheritdoc>.

Here is a use case. I have 4 methods (AddMember, RemoveMember, AddOwner, RemoveOwner) in a controller that share the same parameter and remarks elements. So parameter names and descriptions are identical. And so are remarks (rather verbose, since it includes security requirements, etc, which are the same but need to be repeated). To reduce copy and paste, I'd rather define everything in one method (say, AddMemebr) and have the other 3 reference param and remarks defined for AddMember. The following syntax works fine in other apps (like SandCastle Help Builder), but it does not do anything for Swagger (even if I set options to use IncludeXmlCommentsFromInheritDocs):

/// <inheritdoc cref="AddMember(string, string)" path="param|remarks"/>
/// <summary>
/// Removes a member from a group.
/// </summary>
...
[Route("api/v1/...")]
[HttpDelete]
public ActionResult RemoveMember
(
    string groupId,
    string userId
)

Assuming that I'm correct and this is indeed a limitation, is there a chance the could be more comprehensive and recognize other attributes and member references? Or is there something I am not doing right?