[Feature request]: Support for OpenAPI Description in [ProducesResponseType], [Produces], and [ProducesDefaultResponseType] Attributes

[sander1095]

Is your feature request related to a specific problem? Or an existing feature?

Currently, in ASP.NET Core, the [ProducesResponseType], [Produces], and [ProducesDefaultResponseType] attributes enrich OpenAPI documentation by specifying response status codes, response types, and content types for controller actions. However, they lack support for OpenAPI's description property, which is vital for providing detailed context about the responses.

For instance, when an API returns a 422 status code, it is beneficial to include a description explaining why the error was triggered, enabling better client-side error handling. Currently, there is no standardized way to annotate response descriptions through these attributes.

Although some libraries (e.g., Swashbuckle) offer custom attributes like [SwaggerResponse] that support descriptions, these attributes are library-specific, potentially leading to compatibility and maintenance issues.

I'm working on dotnet/aspnetcore#55656, which adds Description to these attributes. By introducing support for the Description property within these attributes, we can enrich OpenAPI documentation directly in ASP.NET Core in a library-agnostic way, improving developer experience and simplifying API documentation.

Describe the solution you'd like

Swashbuckle.AspNetCore needs to support this new Description property

Additional context

No response

[martincostello]

We can consider supporting this once your PR is merged and we start-up a development branch for .NET 10 (probably Februrary/March 2025 once preview 1 ships).

[github-actions]

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

[sander1095]

This is not stale :) It's been merged and we just need to wait for .NET 10 preview 1. @martincostello , do we want this marked as stale?