You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
3.1.0 - Addition of "summary" to the API info is confusing #2392
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.
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?
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.
@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.
@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.
Activity
MikeRalphson commentedon Nov 2, 2020
See #832 and #1779 for the rationale for this field being added and the differences between
title,summaryanddescription. 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 commentedon Nov 2, 2020
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 commentedon Nov 2, 2020
The line is always between conciseness, clarity, consistency and completeness. The
summaryanddescriptionfields have their different usage descriptions framed in the same manner as for other objects (such aspathItemandoperation). If you can formulate a wording improvement to either or both field descriptions, a PR would be welcome.darrelmiller commentedon Nov 3, 2020
@InfoSec812 When presenting information it is common to have a list view of data and a detail view.
summaryis optimized to represent data in a list view,descriptionis optimized for a detail view.descriptionenables rich text which is useful in documentation.summarydoes not support rich text as that can cause presentation issues when presenting a list of summary values.summaryis 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 commentedon Nov 3, 2020
@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 commentedon Nov 12, 2020
@philsturgeon is going to remove the word "short" from the description of description. Hopefully this is more descriptive.
philsturgeon commentedon Nov 12, 2020
#2408
MikeRalphson commentedon Jun 18, 2021
#2408 was merged, closing this. Thanks all.