Support the use of multiple tags for operations

[steve-nay-sage]

User story.

As a technical writer, I'd like to be able to use multiple tags on operations to have them appear in more than one location in the documentation.

Is your feature request related to a problem?

Depends on what you consider a problem. Stoplight Elements currently ignores all but the first tag in a tags array. Some might think that's a problem.

Describe the solution you'd like

The tags property of an operation takes an array for a reason: to allow flexibility in how information is organized in the documentation. Here's a faked sample-- don't worry about any missing parts:

/pets
get:
summary: List pets
description: See all pets available for adoption.
tags:
- Pets
- Cats
- Dogs

That should result in left column navigation that looks something like this:

Cats
List pets
Dogs
List pets
Pets
List pets

The example would have more impact if there were other tags and operations mixed in there, but hopefully it conveys the idea.

[philsturgeon]

This is a good point. Stoplight has historically used the first tag only, and that may have been a specific requirement at some point, but I do wonder why. I can try and poke some people to find out, but I think this would be a good PR and if there's any conflict we can put it behind some sort of switch at least.

[TekExplorer]

Can, perhaps, multiple tags be used to have nested foldable routes?

[philsturgeon]

The convention is that the first tag is used for navigation structure, then other tags can be used for whatever other purposes people use them for (all sorts of things from team ownership to code generation). Popping those extra tags in to make nested navigation would be a breaking change and potentially a bit messy. Have you ever seen x-tagGroups from our friends over at ReDoc? https://redocly.com/docs/api-reference-docs/specification-extensions/x-tag-groups/ Would something like that solve the use case?

…

Message ID: ***@***.***>

[TekExplorer]

yeah @philsturgeon, i found that a couple days ago. that's the best solution imo
-> #1390

[philsturgeon]

Cool! I think we can close this one down, @steve-nay-sage perhaps you could subscribe to #1390 instead.

[fgabolde]

I'd like to point out that the related issue (introducing tag groups) doesn't solve all the use cases that people use multiple tags for. Sometimes even though we want to design clean APIs, the product requirements are weird, and it results in operations being related to two different concerns. Not Pets > Cats and Pets > Dogs, but more like Pets > Cats and Banking.

Other tools simply make the operation available in both of these tags, e.g. openapi-generator will create the investInCats method in both the Cats service and the Banking service.

Tag grouping can be a complement to this.