Add support for inheritdoc tags #3016

codecooper · 2024-08-08T17:41:55Z

This will recursively scan the XML documentation to gather the first property/attribute that contains the needed value. This change would work automatically without the user having to do anything extra.

This time, the code has been rebased and is ready to bring in. This related to PR #2687.

…cursively using the `inheritdoc` as a reference. Point all XPath queries to this class. Simplify some of the (if) nesting in the XML Comment Filters. Add unit tests for the new InheritDoc updates. some existing tests were converted from `Fact` to `Theory` to accomplish this.

src/Swashbuckle.AspNetCore.Annotations/Swashbuckle.AspNetCore.Annotations.csproj

src/Swashbuckle.AspNetCore.SwaggerGen/XmlComments/XmlCommentsParameterFilter.cs

src/Swashbuckle.AspNetCore.SwaggerGen/XmlComments/XmlCommentsRecursion.cs

martincostello · 2024-08-09T08:53:25Z

src/Swashbuckle.AspNetCore.SwaggerGen/XmlComments/XmlCommentsOperationFilter.cs

+ private const string SummaryTag = "summary";
+ private const string RemarksTag = "remarks";
+ private const string ResponseTag = "response";


Define all these constants somewhere shared for re-use?

I can definitely do this. Do you have a place in particular you prefer? Would you like me to also find and replace all instances of these static string values in the solution?

Something like a XmlCommentTagNames class in this namespace?

I don't think we need to go churning the whole codebase to use it though, particularly outside of this assembly.

src/Swashbuckle.AspNetCore.SwaggerGen/XmlComments/XmlCommentsOperationFilter.cs

src/Swashbuckle.AspNetCore.SwaggerGen/XmlComments/XmlCommentsRecursion.cs

martincostello · 2024-08-09T09:05:40Z

src/Swashbuckle.AspNetCore.SwaggerGen/XmlComments/XmlCommentsRecursion.cs

+ // Try to find the specified tag node within the current member node.
+ var node = memberNode?.SelectSingleNode(tag);
+ if (node != null)
+ return memberNode;


Took me a second to understand what this was doing. Given memberNode might be null I think this would be more clearly written as:

Suggested change

// Try to find the specified tag node within the current member node.

var node = memberNode?.SelectSingleNode(tag);

if (node != null)

return memberNode;

if (memberNode is null)

{

return null;

}

// Try to find the specified tag node within the current member node.

var node = memberNode.SelectSingleNode(tag);

if (node != null)

{

return memberNode;

}

src/Swashbuckle.AspNetCore.SwaggerGen/XmlComments/XmlCommentsRecursion.cs

…les. This was out of scope.

…arameterFilter.cs Moved to a single line as requested Co-authored-by: Martin Costello <martin@martincostello.com>

…perationFilter.cs Add braces to `if` statement Co-authored-by: Martin Costello <martin@martincostello.com>

…equestBodyFilter.cs Clean up formatting. Co-authored-by: Martin Costello <martin@martincostello.com>

…equestBodyFilter.cs Co-authored-by: Martin Costello <martin@martincostello.com>

…chemaFilter.cs Add braces to if statement Co-authored-by: Martin Costello <martin@martincostello.com>

… returns are wrapped in braces. Update string.Format to use `CultureInfo.InvariantCulture`

martincostello · 2024-08-12T08:48:20Z

src/Swashbuckle.AspNetCore.SwaggerGen/XmlComments/XmlCommentsSchemaFilter.cs

@@ -17,27 +19,18 @@ public void Apply(OpenApiSchema schema, SchemaFilterContext context)
 {
 ApplyTypeTags(schema, context.Type);

- if (context.MemberInfo != null)
+ if (context.MemberInfo != null) 


Suggested change

if (context.MemberInfo != null)

if (context.MemberInfo != null)

martincostello · 2024-08-12T08:50:05Z

test/Swashbuckle.AspNetCore.SwaggerGen.Test/Fixtures/FakeControllerWithInheritDoc.cs

+/// <inheritdoc cref = "FakeControllerWithXmlComments" />
+public class FakeControllerWithInheritDoc : FakeControllerWithXmlComments
+{
+ /// <inheritdoc cref = "FakeControllerWithXmlComments.ActionWithSummaryAndRemarksTags"/>
+ public new void ActionWithSummaryAndRemarksTags()
+ {
+ throw new NotImplementedException();
+ }
+
+ /// <inheritdoc cref = "FakeControllerWithXmlComments.ActionWithParamTags"/>
+ public new void ActionWithParamTags(string param1, string param2)
+ {
+ throw new NotImplementedException();
+ }
+
+ /// <inheritdoc cref = "FakeControllerWithXmlComments.ActionWithResponseTags"/>


Only because I've never seen tags formatted this way before, so I think it just looks odd and out-of-place (I haven't seen if there's any already in this codebase 😄)

Suggested change

/// <inheritdoc cref = "FakeControllerWithXmlComments" />

public class FakeControllerWithInheritDoc : FakeControllerWithXmlComments

{

/// <inheritdoc cref = "FakeControllerWithXmlComments.ActionWithSummaryAndRemarksTags"/>

public new void ActionWithSummaryAndRemarksTags()

{

throw new NotImplementedException();

}

/// <inheritdoc cref = "FakeControllerWithXmlComments.ActionWithParamTags"/>

public new void ActionWithParamTags(string param1, string param2)

{

throw new NotImplementedException();

}

/// <inheritdoc cref = "FakeControllerWithXmlComments.ActionWithResponseTags"/>

/// <inheritdoc cref="FakeControllerWithXmlComments" />

public class FakeControllerWithInheritDoc : FakeControllerWithXmlComments

{

/// <inheritdoc cref="FakeControllerWithXmlComments.ActionWithSummaryAndRemarksTags"/>

public new void ActionWithSummaryAndRemarksTags()

{

throw new NotImplementedException();

}

/// <inheritdoc cref="FakeControllerWithXmlComments.ActionWithParamTags"/>

public new void ActionWithParamTags(string param1, string param2)

{

throw new NotImplementedException();

}

/// <inheritdoc cref="FakeControllerWithXmlComments.ActionWithResponseTags"/>

martincostello · 2024-08-12T08:50:53Z

src/Swashbuckle.AspNetCore.SwaggerGen/XmlComments/XmlCommentsRecursion.cs

+namespace Swashbuckle.AspNetCore.SwaggerGen;
+
+/// <summary>
+/// Service to handle recursive retrieval of XML comments from an XPathNavigator.


Suggested change

/// Service to handle recursive retrieval of XML comments from an XPathNavigator.

/// Service to handle recursive retrieval of XML comments from an XPathNavigator.

martincostello · 2024-08-12T08:51:48Z

src/Swashbuckle.AspNetCore.SwaggerGen/XmlComments/XmlCommentsRecursion.cs

+/// <summary>
+/// Service to handle recursive retrieval of XML comments from an XPathNavigator.
+/// </summary>
+internal static class XmlCommentsRecursionService


This doesn't feel "service"-y to me - it's more "helper"-y. I don't think we need recursive in the name either - that feels like an implementation detail to me.

Also the file name should match the type name.

martincostello · 2024-08-12T08:51:59Z

src/Swashbuckle.AspNetCore.SwaggerGen/XmlComments/XmlCommentsRecursion.cs

+ /// An XPathNodeIterator representing the collection of nodes with the specified tag, or null if the nodes are not
+ /// found.


Suggested change

/// An XPathNodeIterator representing the collection of nodes with the specified tag, or null if the nodes are not

/// found.

/// An XPathNodeIterator representing the collection of nodes with the specified tag, or null if the nodes are not

/// found.

Jason Cooper added 2 commits August 8, 2024 11:20

I missed some of the test projects to update to net7.0

b45b575

martincostello reviewed Aug 9, 2024

View reviewed changes

martincostello changed the title ~~Feature/inheritdoc~~ Add support for inheritdoc tags Aug 9, 2024

codecooper and others added 8 commits August 9, 2024 09:44

Remove the RootNamespace and AssemblyName properties on the csproj fi…

1e7f71c

…les. This was out of scope.

Update src/Swashbuckle.AspNetCore.SwaggerGen/XmlComments/XmlCommentsP…

4eddf29

…arameterFilter.cs Moved to a single line as requested Co-authored-by: Martin Costello <martin@martincostello.com>

New files should have file-scoped namespaces.

b377eff

Update src/Swashbuckle.AspNetCore.SwaggerGen/XmlComments/XmlCommentsO…

0f3062a

…perationFilter.cs Add braces to `if` statement Co-authored-by: Martin Costello <martin@martincostello.com>

Update src/Swashbuckle.AspNetCore.SwaggerGen/XmlComments/XmlCommentsR…

1b4881c

…equestBodyFilter.cs Clean up formatting. Co-authored-by: Martin Costello <martin@martincostello.com>

Update src/Swashbuckle.AspNetCore.SwaggerGen/XmlComments/XmlCommentsR…

558065c

…equestBodyFilter.cs Co-authored-by: Martin Costello <martin@martincostello.com>

Update src/Swashbuckle.AspNetCore.SwaggerGen/XmlComments/XmlCommentsS…

fd59ea9

…chemaFilter.cs Add braces to if statement Co-authored-by: Martin Costello <martin@martincostello.com>

Ensured that new lines are at the bottom of the classes. Ensure realy…

72b4ba5

… returns are wrapped in braces. Update string.Format to use `CultureInfo.InvariantCulture`

codecooper requested a review from martincostello August 9, 2024 16:39

martincostello reviewed Aug 12, 2024

View reviewed changes

soroshsabz mentioned this pull request Sep 4, 2024

Add support for <ineritdoc cref="" /> #2687

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add support for inheritdoc tags #3016

Add support for inheritdoc tags #3016

codecooper commented Aug 8, 2024 •

edited by martincostello

Loading

martincostello Aug 9, 2024

codecooper Aug 9, 2024

martincostello Aug 12, 2024

martincostello Aug 9, 2024

martincostello Aug 12, 2024

martincostello Aug 12, 2024

martincostello Aug 12, 2024

martincostello Aug 12, 2024

martincostello Aug 12, 2024

	if (context.MemberInfo != null)
	if (context.MemberInfo != null)

	/// Service to handle recursive retrieval of XML comments from an XPathNavigator.
	/// Service to handle recursive retrieval of XML comments from an XPathNavigator.

		/// An XPathNodeIterator representing the collection of nodes with the specified tag, or null if the nodes are not
		/// found.

Add support for inheritdoc tags #3016

Are you sure you want to change the base?

Add support for inheritdoc tags #3016

Conversation

codecooper commented Aug 8, 2024 • edited by martincostello Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codecooper commented Aug 8, 2024 •

edited by martincostello

Loading