Summary field in Info Object

[rbren]

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)

[RobDolinMS]

@bobby-brennan As there have been a bunch of updates to the spec recently, would you want to take a look and see if the latest version addresses some or all of your concerns?

[rbren]

Thanks Rob. Unfortunately I don't think either concern has been addressed:

• The Info Object only has description, no summary field
• Example Object and Path Item Object have summary fields, but no note about recommended max characters

Proposals:

• Add summary field to Info Object
• Move "SHOULD be less than 120 characters" note from Operation.summary to a higher level, or put that note in each summary field.

Thanks!

[DavidBiesack]

I also suggested adding summary to Tag Object but that was deferred. I prefer the spec be consistent and allow summary everywhere a description is allowed, and vice versa (unfortunately in JSON schem uses title instead of summary so we can't be fully consistent)

[darrelmiller]

Info object has Title. Do we really need Summary as well? Consistency is nice, but consistency for consistencies sake is not all that helpful.

[darrelmiller]

I'm also tending towards not limiting the size of text fields. Where do we stop? Should we define limits on names, keys, email, version, urls? I fear that by fixing the size of every field we are doing busy work that will cause more problems than it will actually solve.

I realize that this may be a controversial position to take, but if we look at other specs like JSON Schema, HTTP, and even JSON itself, the property value sizes are not constrained and people still manage to build tooling that works.

[whitlockjc]

I agree with @darrelmiller.

If it ends up becoming the official stance, I would advocate for removing summary and using description as the place to describe objects. Of course, tooling will have to handle the fact that this could be plain text or GFM but to me, that's a tooling issue (and an easy one to solve since many libraries out there handle this).

[rbren]

Ditching the character limit makes sense to me, though I would suggest dropping it from Operation.summary as well for consistency. Usually info.description contains a long introduction to the API, with e.g. instructions on getting an API key. This isn't appropriate as a summary in an API gallery. Just stripping the markdown syntax and truncating makes for a pretty poor UX. API owners need a way to briefly specify what their API does, in addition to the long-form instructions they currently put in info.description (which, based on usage, could probably be renamed info.documentation). On Apr 26, 2017 4:41 PM, "Jeremy Whitlock" <notifications@github.com> wrote: I agree with @darrelmiller <https://github.com/darrelmiller>. If it ends up becoming the official stance, I would advocate for removing summary and using description as *the* place to describe objects. Of course, tooling will have to handle the fact that this could be plain text or GFM but to me, that's a tooling issue *(and an easy one to solve since many libraries out there handle this)*. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#832 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AHQmReGh4WwSGHVQI2ThTteljqNW-JLSks5rz6wHgaJpZM4Ks7MU> .

[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 ;)

[ioggstream]

@MikeRalphson can I send a PR for this? Which is the right branch to push it?

[MikeRalphson]

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

[ioggstream]

FYI @bobby-brennan just made a PR with that #1779

[rbren]

Thanks! Excited to see this moving forward.