Support for associating XML Comments with custom tags defined using TagsAttribute

[yingxinj]

Description & reference issues

As of .NET 6.0, Swagger/OpenAPI supports using TagsAttribute to rename each group of endpoints, overriding the default value of the controller name. (See also e.g. the top voted answer by Raul on this SO question)

The existing implementation of Swashbuckle's XmlCommentsDocumentFilter associates the controller's <summary> XML comment with the controller name. It currently has two limitations:

1. It does not support using TagsAttribute - it only links the summary node with the controller name. See the last four comments on TagActionsBy custom tag or controller name #467, these last comments refer to the new TagsAttribute instead of TagActionsBy.

2. It only adds tags for controllers with a summary node. If the user has summary nodes for some controllers but not others, then the root tags object will only include a partial list of tags. This results in the side-effect that tags are not displayed in alphabetical order. Instead, tags with descriptions are displayed first, followed by tags without descriptons. Related issues:

   • Controllers not sorted alphabetically when using includeControllerXmlComments #2162
   • Unable to change group order with OrderActionsBy when only some group have description  #1757

Another linked issue #2530 is a result of both these limitations.

This PR fixes both these issues. If IncludeXmlComments is true:

• then the resulting tag names & descriptions will support the new TagsAttribute, falling back to the default (controller name) if TagsAttribute is not used.
• then the resulting root tags object will contain all controller-level tags, regardless of whether they have an XML summary node or not. Those without a summary node will not have any "description" field.

Tests

Tests are included for the target framework .NET 6.0, which supports TagsAttribute. The SwaggerGen.Tests project currently only targets .NET 6.0, so I did not add unit tests for earlier frameworks. I built the project in .NET 5.0 and did a manual test of this case to check it works.

Potential improvements

This PR still has some limitations:

• TagsAttribute theoretically allows you to specify more than one custom tag e.g. by [Tags("first tag", "second tag")] however I don't see this as a primary use case in generating the swagger file, and there is no way of providing separate XML summaries for the two tags, so this is not supported in this PR - only the first tag is supported.
• TagsAttribute can be specified at the method level, if so, such tags would still be omitted from the root tags object.

If it's actually useful, I would be happy to add support for these cases.

[NilkOne]

Great !
When will this fix added on NuGet?

[silkfire]

@domaindrivendev Any ETA on this?

[Skintkingle]

We could really do with this change.

[sirmeepington]

This would be a lifesaver 👍

[DenKn]

This fix does not cover all cases. For example it won't work

 public abstract class ConfigurationControllerBase : ControllerBase
{
}

[Tags("ConfigurationController ")]
public class ConfigurationController : ConfigurationControllerBase 
{
}

[martincostello]

Thanks for contributing - if you'd like to continue with this pull request, please rebase against the default branch to pick up our new CI.

[yingxinj]

Thanks @martincostello, I've rebased against your latest master branch.

Edit: apologies, I've realised that the build is failing, I'll look into it when I have another chance.

[martincostello]

Let's make TagsAttribute and TagActionsBy <see .... /> references in these two comments.

[martincostello]

It would be better to only add this polyfill for the TFMs that need it. Also, can it be internal?

[martincostello]

Suggested change

	private class ControllerInfo
	private sealed class ControllerInfo

[martincostello]

This looks like it'll throw an exception if Tags is empty or null.

[github-actions]

This pull request is stale because it has been open for 60 days with no activity. It will be automatically closed in 14 days if no further changes are made.

[github-actions]

This pull request was closed because it has been inactive for 14 days since being marked as stale.