Vendor extension suggestion: 'x-description-extended' for responses

[cmeeren]

I sometimes need to write a lengthy explanation for a specific response (possibly with lists and other formatted text). AFAIK description is the only field for this, but a lengthy description here doesn't look too good with ReDoc - it seems like the response description is intended to be kept short.

Unless I'm missing an existing way to accomplish this, I suggest a simple vendor extension x-description-extended for response objects, functioning similarly to description except that the contents are placed "below the fold". See the image below for an example of where (roughly) I'd like it placed.

See the below image

[RomanHotsiy]

I think x-summary + description would be better.
I can change ReDoc to render only the first paragraph of description in the button and the rest under
And if x-summary is provided, x-summary would be rendered in the button and description below.

What do you think?

[cmeeren]

I like x-summary, that's much better (especially since I suggested an official summary field in the OAS repo).

As for the first paragraph vs. the whole description, I'll leave that to you. I don't have any problem with the current behavior. If you choose to render only the first paragraph, you should perhaps add an indicator that the description is incomplete (something like ...).