Add description to ProducesResponseTypeAttribute

[mu88]

Is there an existing issue for this?

• I have searched the existing issues

Is your feature request related to a problem? Please describe the problem.

When using the ProducesResponseTypeAttribute, the generated OpenAPI doc does only contain a very basic description (Success, etc.). When describing something more elaborate, XML documentation comments have to be used, e. g. /// <response code="200">describe something important</response>. But the value for the code attribute only accepts pure numbers, not enums - I cannot write /// <response code="HttpStatusCode.Success">describe something important</response>. This makes refactoring harder to accomplish.

Describe the solution you'd like

Therefore it would be great to have a property like Description on the ProducesResponseTypeAttribute. This property could be picked up by Swashbuckle/OpenAPI.

The result would look like this: [ProducesResponseType(HttpStatusCode.Ok, "describe something important")]

Additional context

No response

[captainsafia]

@mu88 Thanks for reporting this issue!

Therefore it would be great to have a property like Description on the ProducesResponseTypeAttribute. This property could be picked up by Swashbuckle/OpenAPI.

At the moment, we're not planning on making any changes related to OpenAPI in the response type attributes. A lot of future work in this area is centered around what we are pursuing in #40676.

Now, specifically as it relates to the XML comment, I would recommend filing an issue on the Swashbuckle repo. The logic for XML-based documentation lives in Swashbuckle so your best bet for identifying a fix lives there.