3.1.0 - Addition of "summary" to the API info is confusing

[InfoSec812]

What does "summary" give us that "description" does not? Perhaps "summary" could just be an alias for "description"?

[MikeRalphson]

See #832 and #1779 for the rationale for this field being added and the differences between title, summary and description. The OAS does not have the concept of aliases, and I for one would not like to see them introduced.

What do you find confusing?

[InfoSec812]

I think that some of the context from those two issues could help clarify in the 3.1.0 document. Right now, I did not understand that from what I read in the standard. If it is explained somewhere else, then perhaps a link to that explanation?

[MikeRalphson]

The line is always between conciseness, clarity, consistency and completeness. The summary and description fields have their different usage descriptions framed in the same manner as for other objects (such as pathItem and operation). If you can formulate a wording improvement to either or both field descriptions, a PR would be welcome.

[darrelmiller]

@InfoSec812 When presenting information it is common to have a list view of data and a detail view. summary is optimized to represent data in a list view, description is optimized for a detail view. description enables rich text which is useful in documentation. summary does not support rich text as that can cause presentation issues when presenting a list of summary values.

summary is an optional field so you can choose not to use it if it is not useful for your scenario. Adding summary to info was a request from the community and it created consistency with other objects in the specification. This felt like sufficient justification for its inclusion.

[InfoSec812]

@darrelmiller Now that I have had it explained by @MikeRalphson I agree. What I would like to do, and thus the PR, is make that obvious to everyone who reads the specification/standard by adding the definition and providing links to that information.

[darrelmiller]

@philsturgeon is going to remove the word "short" from the description of description. Hopefully this is more descriptive.

[philsturgeon]

#2408

[MikeRalphson]

#2408 was merged, closing this. Thanks all.