Summary field in Info Object

Several objects have both a description and a summary field. The distinction seems to be that summaries are plaintext and should be <= 120 chars, while descriptions are markdown and can be arbitrarily long.

I’d like to have an optional summary field in the Info Object e.g. for display in API Galleries. Currently to achieve this on AnyAPI we strip HTML/md out of the description field and truncate it, which isn’t great.

I’d also like to see a higher level note about summary vs. description and add the “SHOULD be <= 120 characters” to each summary field (right now it’s just mentioned on operation.summary)

[ioggstream]

Revamping the thread, as after many ramblings I had to add an x-summary to my definitions.

Proposal:

• add an optional info.summary to be a service description (eg. for catalog purposes)
• not enforcing limit.

To make an analogy with a product:

  title: "Ferrari Testarossa"
  summary: "A 12-cylinder mid-engine sports car manufactured by Ferrari"
  description: |-
    The whole wikipedia page ;)

[MikeRalphson]

It’s a minor (non breaking) change so the v3.1-dev branch would be the one.