Controllers not sorted alphabetically when using includeControllerXmlComments

[lonix1]

Environment

aspnet: 5.0.301
Swashbuckle.AspNetCore: 6.1.4

Background

I created a minimal swashbuckle implementation. All I have is:

o.IncludeXmlComments(path, includeControllerXmlComments: true)
o.CustomSchemaIds(x => x.FullName);

And I added <summary> xml comments to my controllers.

Problem

If I use includeControllerXmlComments:false then the controllers are sorted alphabetically.

But if I use includeControllerXmlComments:true then the controllers are not sorted alphabetically.

[lscorcia]

+1 for this.
As a workaround, you can use the following document filter:

/// <summary>
/// Workaround for https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/2162
/// When adding XML controller descriptions to the swagger description document,
/// controllers are listed out of alphabetical order.
///
/// This filter explicitly reorders them.
/// </summary>
public class TagReorderDocumentFilter : IDocumentFilter
{
  /// <summary>
  /// Allows customization of the swagger description document
  /// </summary>
  /// <param name="swaggerDoc">The generated swagger description document</param>
  /// <param name="context">Context information</param>
  public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
  {
    swaggerDoc.Tags = swaggerDoc.Tags
      .OrderBy(tag => tag.Name)
      .ToList();
  }
}

To apply the filter add it during Swagger initialization:

builder.Services.AddSwaggerGen(config => {
  ...

  // Workaround: After adding XML controller descriptions, they are listed out of alphabetical order
  config.DocumentFilter<TagReorderDocumentFilter>();
});

[lonix1]

In newer versions, this seems to work without the need for any customisation.

ASP.NET Core 5.0.11
Swashbuckle.AspNetCore 6.2.3

[lscorcia]

Unfortunately the issue is still present. ASP.NET Core 6.0 + Swashbuckle.AspNetCore 6.3.0. I will open a new issue.

[lonix1]

Hey @lscorcia I've reopened for you.

[lscorcia]

Thanks @lonix1 ! I prepared a small repro project at https://github.com/lscorcia/UnsortedControllersRepro . Please let me know if you need any additional information.

[lonix1]

@lscorcia Sorry to disappoint but I'm not a repo member... I was the one who reported the original problem. 😃 Hope you get your problem fixed.

[yingxinj]

@lscorcia I think this is a side-effect of the fact that if you add includeControllerXmlComments:true only controllers with XmlComments are added to swaggerDoc.Tags object in the document filter example above, so that the controllers with XmlComments and those without will be sorted separately. My open PR linked above resolves this issue, please let me know if it is helpful.

[martincostello]

#2565 should fix this.

[martincostello]

Duplicates #1757