Suggestion for new 'summary' field on 'response' object

[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 in most documentation renderers I've tried (e.g. Swagger UI, ReDoc). In those tools, response.description seems to be intended to be kept short, almost as a "heading" for the response.

I've posted an example with a screenshot on Redocly/redoc#500.

It would be great to have a summary field on the response object, so that renderers can use this as a summary for the response, allowing description to be used for a lengthier explanation where needed.

[handrews]

Hmmm... per JSON Schema, title should be the short heading, description should be the long text. This might be arguably more of a tooling issue?

[cmeeren]

I might have misunderstood something, but the only mention of a title field I can find in the 3.0.1 spec is for the Schema object and the Info object.

[handrews]

@cmeeren oh, nope, it's me who misunderstood. Carry on!

[handrews]

Although if there will be a short and long form, I'd recommend following JSON Schema since it is being used in the Schema Object and already does this- title is short, description is long. If description were the short field elsewhere that would be very confusing. I suppose the point of this issue is that it already is.

[cmeeren]

Sorry, I don't get what you mean. Let me try to clarify.

Response objects currently only have one free-text field for describing them, namely description. I would like two fields – one for a short summary/title , and keep decription as is. Tools can then use description as a substantial description of a response, and summary/title (whichever) as a short "heading" for the response (e.g. displayed together with the status code).

As for calling the new field summary or title, I suggest summary, since it's used on Path Item and Operation objects, which are close to Response objects (it's also used on Example objects). title is only used on the top-level Info object.

[handrews]

As for calling the new field summary or title, I suggest summary, since it's used on Path Item and Operation objects, which are close to Response objects (it's also used on Example objects). title is only used on the top-level Info object.

Yeah, that makes sense. Sorry, having an off day apparently.

[LasneF]

@handrews any news on this one ?

we should have a standard and constant pattern here about summary / description , that would apply every where

could easily be enhanced in a 3.1.1 or in a 3.2.0

or goes inside the 4.0 with full alignment with json schema , and drop support of summary for "title"

this would so avoid the x-summary for instance in redoc , and would allow nicer rendering