Add a Description property to the ProducesResponseTypeAttribute<T>

[Eirenarch]

Background and Motivation

When using Swashbuckle to generate Swagger for an API I found myself choosing between using the ProducesResponseTypeAttribute and xml doc with nodes. If I use the attribute I don't get to write my own description text, if I use the XML docs I don't get to specify the return type. I've opted into using the XML docs because in most cases the response type is ProblemDetails and the important thing is the human-written description of when a certain status code happens. While it is probably possible to make the tooling in a way that reads both the xml status code and the ProducesResponseTypeAttribute it requires much more effort to implement compared to a simple solution - adding a string? Description property to the ProducesResponseTypeAttribute

Proposed API

Add a string? Description to the ProducesResponseTypeAttribute and maybe to the ProducesResponseTypeAttribute. Maybe add a constructor overload that accepts it

Usage Examples

[ProducesResponseType(409, description: "Some conflict with existing items")]
public async Task CreateCustomer(CustomerCreateDto customerCreateDto)

Risks

There is a risk that someone already implemented the proper tooling to read both the XML docs and the ApiExplorer data and there might be a clash but probably one would just override the other

Additional Notes

To maximize the usefulness of this property it should be surfaced in the ApiExplorer data

[captainsafia]

@Eirenarch Thanks for filing this issue! I believe this is a dupe of #55656 which we need to move from api-suggestion to api-ready-to-review. For now, I'll close this as a dupe and recommend following the issue for further updates on this new API.

[dotnet-policy-service]

This issue has been resolved and has not had any activity for 1 day. It will be closed for housekeeping purposes.

See our Issue Management Policies for more information.