ASP.NET Core OpenAPI generator does not populate tag.description; controller XML comments and DescriptionAttribute are ignored
- 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
Assessment
This issue has not been assessed yet.