ASP.NET Core OpenAPI generator does not populate tag.description; controller XML comments and DescriptionAttribute are ignored

[itbencn]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

• In ASP.NET Core Web API targeting .NET 10, the generated OpenAPI document does not include tag.description for tags. By default, tag.name is derived from the controller class name or [Tags] attribute values, but controller XML comments (summary/remarks) and [Description] attributes are not used to populate tag.description.

• Many OpenAPI documentation UIs (Swagger UI, Scalar, Redoc) display tag.description and rely on it to provide meaningful group-level documentation. Without tag.description, the generated docs are less informative.

Expected Behavior

• The generator should populate tag.description using existing metadata already available in controllers and attributes, so documentation UIs can display meaningful group descriptions.

Steps To Reproduce

1. Create a new ASP.NET Core Web API project (NET10).
2. Enable OpenAPI generation (built-in OpenAPI support).
3. Add a controller with XML documentation comments at the class level, e.g.:

/// <summary>
/// ExampleInterfaceGroup
/// </summary>
/// <remarks>Some sample interfaces are placed here for testing</remarks>
[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
    //...........

    /// <summary>
    /// ExampleInterface
    /// </summary>
    /// <returns></returns>
    [HttpGet(Name = "GetWeatherForecast")]
    public IEnumerable<WeatherForecast> Get()
    {
        //...........
    }
}

4. Optionally, apply [Tags("Weather")] on actions or controller.
5. Build with XML documentation enabled and inspect the generated openapi.json.

Exceptions (if any)

Actual behavior:

• When [Tags] is not used, the generator maps the controller class name to tag.name, but no value is produced for tag.description.
• When [Tags] is used, each tag string is mapped to tag.name, but tag.description remains empty.
• Controller-level XML comments (summary/remarks) have no effect on tags in the generated OpenAPI document.

Rationale:

• OpenAPI Tag Object supports both name and description. Adding tag.description improves the readability and usefulness of generated docs without breaking existing APIs.
• Multiple third-party UIs support and display tag.description.
• The framework already has several sources of descriptive metadata (XML docs, [Description]) that could be mapped to tag.description.
  

Proposed solutions (non-breaking preferred):

• Use existing [Tags] together with [Description] to populate tag.description:
  • If a controller or action has [Tags("Foo")] and a [Description("...")], map the description to the tag.description of "Foo".
  • If [Tags] is absent, use the controller’s [Description] for the default tag associated with the controller.
• Use controller XML documentation to populate tag.description:
  • Map controller to tag.description when available.
  • If remarks is absent, fall back to controller summary for tag.description.
• Optional mapping of controller XML documentation to both name and description:
  • Map controller summary to tag.name and map remarks to tag.description when [Tags] is not provided. This could be opt-in via configuration.
• Consider (if acceptable) extending [Tags] with a Description property or introducing a new attribute for tag descriptions (e.g., [TagDescription("Foo", "desc")]). This is more invasive and may not be preferred but would provide precise control.
  

Suggested precedence and conflict handling:

• For endpoints without [Tags]:
  • tag.name = controller class name
  • tag.description = controller remarks or summary or [Description], in that priority order.
• For endpoints with [Tags]:
  • tag.name = values from [Tags]
  • tag.description = controller [Description] or XML remarks/summary , applied to those tags.
• If multiple controllers contribute the same tag name with different descriptions:
  • Use the first non-empty description encountered and log a diagnostic in development, or provide a configuration option to choose resolution strategy.

.NET Version

10.0.100

Anything else?

No response

[itbencn]

tag.description display results

Additionally, I discovered an interesting feature:deprecated with ObsoleteAttribute

[itbencn]

Meanwhile, for enumeration types, there is no array of enumeration values and descriptions in the generated OpenAPI documentation