v3.2: Support summary alongside every description

[handrews]

NOTE: For this PR, if everyone reacts with "yeah let's do this!" then we should put it in 3.2. If it's controversial, I'm fine with bumping it for further consideration. I spent about 10 minutes on this PR, which was faster than asking anyone if I should do it.

Fixes #1591.

This adds a summary field to every Object that has a description field but did not already have summary. As @LasneF noted in the linked issue, it makes sense for us to be consistent with these fields.

• schema changes are included in this pull request
• schema changes are needed for this pull request but not done yet
• no schema changes are needed for this pull request

[miqui]

@handrews >> if everyone reacts with "yeah let's do this!" then we should put it in 3.2

+1 for this and IMHO should not be controversial itself. I believe this makes the overall spec more consistent.

[lornajane]

I don't think this makes sense in every context, honestly, people don't use one field for words, so I don't think the users need two (parameters are a particular bald patch). However we already made this change for tags, and I think for security schemes, servers and responses it does make sense partly because those are often displayed in a condensed, pick-one format, which is where the summary fields are most needed.

[handrews]

@lornajane my sense from the issue is that

1. It definitely makes sense for more places than we had it in 3.1
2. It is the lowest-effort sort of field to support
3. It's easier to just be consistent than to debate every possible location in detail (example: You did not include
4. Consistency in the data structure allows consistency in UIs and other handling

That said, whatever the TSC decides on this is fine with me. I'm not interested in debating this Object by Object so if you and others want to I'll leave you to it. I think this comment covers everything I have to say on this one.

[lornajane]

My personal opinion is that if we're not prepared to consider this object-by-object, we should not merge this as-is, but instead revisit when we're ready to look at it all in detail.

[miqui]

honestly, people don't use one field for words,

@lornajane Not sure what you mean by this? On more than one occasion, I have had tech writers (involved in API gov initiatives yay!!) share that summary and description are both essential components in technical documentation, (and more so when the API is to be eventually mature to be a product on its own).

I don't in anyway presume to be a tech writer, but at least to me their point made a lot of sense.

I would rather use a summary attribute than to leverage the new name attribute in the server object, for example.