Add a path-level description element to pathItemObject

[erikvanzijst]

In swagger 2 one can only add description elements to PathItemObjects. Except, it might make sense to also allow a path level description.

Similar to how web frameworks often provide both class-level and method level doc strings.

[whitlockjc]

I think that's a great idea. Probably any place you can have a vendor extension, you should be able to throw in a documentation string.

My 2 cents.

[erikvanzijst]

Agree. A little like how XML Schema allows doc strings in pretty much every single element.

[webron]

That was the case in 1.2 and earlier versions where operations were grouped by path, and the description was available at that layer.

Since in 2.0 the grouping has changed to tags, the description also moved to that level.

I'm not sure allowing a description property everywhere would necessarily make sense. What are you explaining at the path level that you wouldn't explain at the tag level?

[whitlockjc]

I somewhat agree but I think this is somewhat part of the problem. In some places, we have a description property and in others we have tags. It would be nice to have a consistent construct for all necessary levels to throw in some human readable context. I know we already have most of this so I'd need to do another review to see if there are places where we're missing some.

[webron]

tags and description are different. You can have tags without a description, it's just a grouping mechanism.

And I think you hit the mark - throwing in human readable context. However, since paths do not provide the context but rather the tags, then we're in the right place.

Try to think of this also from the tooling point of view - the way the spec is built right now, the tools will have no value to that level of description.

Perhaps I'm missing something, so really am looking for the other point of view.

[tedepstein]

I'm finding this a bit confusing.

@erikvanzijsterikvanzijst wrote:

In swagger 2 one can only add description elements to PathItemObjects. Except, it might make sense to also allow a path level description.

I'm not sure what "path level description" means. The Paths Object is just a map of Path Item Object, keyed by path. And there's only one Paths Object, contained by the top-level Swagger Object.

So if you were to add a description to the Paths Object, what exactly would you be describing? And how would this be distinct from a description that you'd provide in /info/description?

@whitlockjc wrote:

Probably any place you can have a vendor extension, you should be able to throw in a documentation string.

Generally agreed, and I'm not sure why Swagger allows for vendor extensions on the Paths Object. Again, not clear what you'd want to put here that's distinct from vendor extensions on the containing Swagger Object.

@webron wrote

Since in 2.0 the grouping has changed to tags, the description also moved to that level.

Makes sense if the intent is to document a related group of operations, but it's not clear that this is what @erikvanzijst was trying to accomplish.

[webron]

@tedepstein - thanks for bringing that up. I think there's a bit of a confusing here. I believe (though not speaking on his behalf) that @erikvanzijst meant that he expect there to be a description at the Path Item object and not only at the Operation object. My comments were based on that, but reading back the original comment after your comment, I could have gotten it wrong.

Like you said, I don't see any added value to have a description at the Paths object.

[tedepstein]

@webron, @erikvanzijst Oh! That makes much more sense. And if that was the intent, then I would agree, it makes a lot of sense IMO to allow a description on the Path Item Object. (And I'd suggest renaming this issue to clarify that it's Path Item Object, not PathsObject.)

My reasoning: The Path Item Object generally describes a resource, in the RESTful sense. When it's used in this manner, it's not just a group of operations, it's an abstraction of some tangible or recognizable thing that we'd like to be able to describe, for human-to-human communication purposes. The state and the operations are all subordinate to this abstraction, and the description should help put those mechanical elements in context for the API client developer.

You might be able to do this in some cases by defining a resource-specific tag (or "Path Item Object-specific tag") that you apply to all of the operations within that resource/PIO. Then you could document the PIO indirectly by adding a description to the tag that applies to all of the operations within that PIO. But what if you also want to apply other tags to subsets of operations within that resource, or across resources? Will this confuse the tools?

Nobody knows, because there's no standardized handling of tags by tools, AFAICT. A tag is a grouping construct, and can attach documentation. Tags can be ordered globally by declaring them in the Swagger Object's tags array. But I don't see any documented rules for how tools are supposed to process those tags, so it's hard to say that it's really safe to do something like what I described above, using one tag to document all operations within a PIO, and also using other tags to document (or group, or order) subsets of those tags.

So based on what I understand so far, I'd be inclined to give this a +1. Attaching documentation directly to the PIO seems much more straightforward and reliable than attaching it to a tag.

[webron]

But what you're suggesting, @tedepstein, is to have two different ways to group operations. It's okay to say that, of course, but it is a change in the current structure. In my original comment I'd mentioned that we have dropped the concept of a resource in Swagger in favor of tags, and it was intentional. We can change it back, or can do both, but there needs to be an a good basis for either. You mentioned the 'RESTful sense' but we don't really follow one specific concept or another, and tags do offer a way to group by resources like you mentioned.

I'm not doubting the value of adding a description, I'm just saying there's already a way to do so. Adding another mechanism could just complicate the tools, specifically documentation tools. Say you have both tag descriptions and 'resource'-level descriptions - documentation-wise, how would you display that to the user? I just can't think of a way to do that in a useful way to the end user (and not referring to a specific tool).

Also, as for the claim for a resource-based documentation, a PIO is not equivalent to a resource. In 1.2 and previous versions, each file represented a resource. But in 2.0, since all are poured under one Paths Object, you will have one PIO representing /books and one PIO representing /books/{bookId} - and those two are in fact one 'resource' in the RESTful sense. So... really not sure how this is going to work.

[erikvanzijst]

In my original comment I'd mentioned that we have dropped the concept of a resource in Swagger in favor of tags, and it was intentional.

I am strongly on the side of @tedepstein here, who laid out my position far more elegantly than I could have (including correcting my typo in the subject).

I don't think that tags are a substitute for resource-specific doco. This because tags are also used to bind groups of different resources (see our issue tracker tag that combines 8 or so very different resources) and mixing resource specific tags with wider (issue-tracker-like tags) turns into a mess as tags have no hierarchy or organizational features.

[webron]

Okay, in that case, I would suggest raising the issue in a different way and that's to revisit the way operations can be grouped rather than adding a description at the PIO, especially since a PIO is not equivalent to a resource.

I would argue that tags can still be used because you can have multiple tags. You may then say that while that's true, that may lead to some form of duplication as tags have no hierarchy. We may conclude from that the requirement is to have some sort of hierarchical grouping (which could get complicated) or perhaps another form of structure. I think mixing description in tags and PIOs may also be confusing to some users when looking at the structure of the doc.

If we do stick to using tags (and I'm not saying we should), we could ease up the definition process by allowing the definition of tags in the PIO level as well as the operations themselves, and those tags would be inherited by all operations under it. Less typing, easier to see and understand to a user reading the spec directly.

[erikvanzijst]

we could ease up the definition process by allowing the definition of tags in the PIO level as well as the operations themselves, and those tags would be inherited by all operations under it.

I'm not sure that's necessarily related to the issue, but a good idea nonetheless.