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.

[webron]

Well, right now, for the purpose of documentation alone, tags do solve the issue you bring up. Having tags at the PIO level would just make it easier.

[erikvanzijst]

Well, right now, for the purpose of documentation alone, tags do solve the issue you bring up. Having tags at the PIO level would just make it easier.

I don't really see that.

We use tags to group resources on a more logical/functional level. E.g. issue_tracker that contains 8 distinct resources and pullrequests, etc.

If I were to also use tags to identify individual resources, then these feel like different things. issue is a resource, issue_tracker is not and so I'm hesitant to go in that direction. Maybe that's the essence of our mental models differences?

[webron]

I know it doesn't seem that way, but to me we are saying the same thing.

You're saying you have issue_tracker, which let's say has resources like pullrequests, issues and.. I don't know.. labels. You can have one tag for each, and you can apply multiple tags to each, and get the end result that you want - documentation to the individual 'resources' and documentation to the group as a whole. Documentation-wise, the solution is there. Grouping is grouping, and there's no real conflict in grouping the operations in more than one way.

However, from what you're saying and from what @tedepstein was saying, you're saying that the grouping potentially misses another level of abstraction. You're saying - "I want to be able to group operations as resources, and resources as a logical unit". So the real issue here is not that you don't have a way to provide the documentation you want, but rather that you don't have a way to represent the structure that you want. You don't want to say, I have different groups - issue_tracker, pullrequests and issues, and those groups overlap; you want to say I have issue_tracker and under it there are two distinct groups pullrequests and issues, and with that structure anything under issues is also under issue_tracker. I could be way off here, so please correct me if that's not what you're saying.

But if that's what you're saying, then the core issue here is not "I want to be able to add documentation to PIO" but rather "I want a better way to control the grouping of my operations", with the understanding that you can already document a group of operations with the current solution. I hope the distinction between the two is clear. If not I'm afraid I'd have to go into graphs and diagrams and you don't want that ;)

I can go into a suggestion as to how you can actually solve that form of grouping with the current limitations, but before I do that, I want to make sure we're on the same page.

I'll just add that not all users are looking for such a distinction and adding that layer of grouping should be optional, if that's the path we choose to take.

[tedepstein]

@webron , a confession: I still have things I need to learn about Swagger/OAI, even though I'm working with it pretty extensively now. So, getting up the learning curve as fast as I can. ;-)

I can see that the proposed change introduces some complications, given how tags are used to organize the presentation in the Swagger-UI. I'll think of that as the "de facto standard" for tag interpretation, which I can try to summarize, based on observed behavior:

• Swagger-UI views the Swagger spec as a collection of operations, categorized by tags in a many-to-many relationship. PIOs are not a primary organizing construct, they're more like shared metadata attached to a set of operations.
• Tags themselves are an ordered set, where the first application of a tag to an Operation appends it to the ordered list. (Tag definitions don't append the tag to the list.)
• Swagger-UI displays operations in tag groups. Untagged operations, if there are any, appear in a "default" group. Then the explicitly applied tag groups are shown, with accompanying documentation if provided.
• Each tag group contains its associated operations, including the operation description, parameters, interactive form, etc.

What's odd here is that the Swagger-UI view seems so different from the object structure within the Swagger spec...

I think a lot of Swagger users would say that a PIO bears a striking resemblance to a resource, to the point that they'd be surprised to hear your statement that it's not.

It is an object, uniquely identified by a path within an API, and it contains a set of operations.

I'm not sure what ingredient is missing from that formula which, if added, would make it a resource. Maybe stronger semantics around the state lifecycle. Maybe a single data structure that all requests and responses (or certain ones) use by default, or by convention. I guess those things would make a PIO even more resource-like.

But my point is, even without those things, there's already a strong resource smell to a PIO, and I think many Swagger APIs use PIOs as resources. Even if they don't, the line between a PIO and a resource seems very thin, maybe even academic. I'm interested to understand your perspective on this, but regardless of whether it's a resource or not, the PIO seems like a strongly cohesive organizational structure within the Swagger spec.

But it's not used to organize the Swagger UI. How to resolve it? Not sure. I will catch up on the latest comments, have a think about it, and post back with some thoughts.

[erikvanzijst]

I realize pulling swagger-ui into a spec discussion is dicey, but the way it deals with tags is that is essentially produces a massive, flat, single-page list. In our case that would put the issue resource on the same level as the more logical concept issue_tracker.

Maybe that's a swagger-ui problem that we could work around, rather than changing the spec, for instance by using dotted tags (issue_tracker (that has high-level doco), issue_tracker.issue (doco on a specific resource), issue_tracker.milestone, pullrequest.comment, etc) and then have the UI create hierarchy that way.

That might work and is certainly something we could to today provided we forked swagger-ui, or wrote our own, but it wouldn't necessarily help others.

[webron]

Parent issue: #560.