description/summary for Paths Object

[handrews]

Discussed in #3532

^{Originally posted by kentbulza January 28, 2024}
This seems like an obvious gap to me, but I want to see what were the philosophical reasons for it. Perhaps because the webhooks object is newer, it just wasn't as obvious at first that the info object can be awkward? The issue is there may be very different global(esque) descriptive text for all the paths vs. all the webhooks.

---

The concern here is about describing Paths and Webhooks separately. It's possible to put each in separate documents with separate Info Objects, but it is not possible to reference an entire Paths Object (or the entire contents of the webhooks field, which isn't a named Object in 3.1). I could see solving this by either adding these fields (they cannot be confused with path templates, although that doesn't help with the object under webhooks) or the much larger change of allowing referencing groups of Paths (which might be deemed too big to do prior to Moonwalk

[baywet]

@ralfhandl can you assign this one to me please?

[ralfhandl]

I suggest not doing this and instead let Moonwalk solve this problem.

Rationale

The original issue states that the Info Object may not be a good place to describe both paths and webhooks:

The issue is there may be very different global(esque) descriptive text for all the paths vs. all the webhooks.

I don't see this as a problem because info.description can use CommonMark and have text applying to the whole API plus sections specific for paths and webhooks.

We cannot add description etc. to the webhooks dictionary because they may be dictionary keys.

We could theoretically add description etc. to the paths dictionary (aka Paths Object) because luckily the keys of that dictionary need to start with a /, but it still feels odd adding this asymmetry.

Also adding these fields only for the paths would kind of skew info.description away from being a description of the whole API towards being a description mainly for the webhooks (in APIs that have them).

[baywet]

I don't have a strong opinion on this. I was simply volunteering to do the grunt work.
You can un-assign this from me since I have work on the additional operations for the time being.

And in the meantime, maybe @handrews can chime in on additional context/rationale for this.

[lornajane]

I also suggest that we do not implement a change like this in 3.x (thanks @ralfhandl for the good reasoning). If the paths and webhooks don't belong together then separate them - or use heading markdown in the info section to include information about each part. I will close this issue now, but please feel free to request it be re-opened if we're missing something.