dotnet / dotnet/aspnetcore

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

Open
#64,345 4 comments 5 reactions 0 assignees View on GitHub
area-mvc feature-openapi
Dominant language
C#
Stars
38.4k
Forks
10.9k
Avg merge
2d 10h
Merged PRs (30d)
281

Description

### Is there an existing issue for this?

- [x] 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.:

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

///
/// ExampleInterface
///
///
[HttpGet(Name = "GetWeatherForecast")]
public IEnumerable 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_

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.