Grouping Endpoints into Collections

I would like some help if possible - I’m trying to group endpoints in our ‘resources’ section into collections, to make it easier to read.

As you can see here - it’s working nicely for the ‘Mapping’ part of our ‘API Reference’ section.

We did this by grouping these items in the toc.json

I’m happy with this.

NOW the problem.

For our ‘Resources’ section, we simply add a reference to the API’s openAPI yaml file:

This, as far as I can tell, autogenerates our resources section:

The issue, as you can probably see here (you may need to expand the image), is that we have a confusing bunch of endpoints now in the ‘Mapping’ section, making them hard to read and understand. I want to group the elements like the previous section, into ‘Advertiser Mapping’, ‘Brand Mapping’, ‘Destination Mapping’ and ‘Channel Mapping’.

So - how do I create this sub groupings, when these items are autogenerated by Stoplight?

  • Should I use tags? And if so, how do I get the resources to group according to tags?
  • Do I write these collections directly into the JSON specification of peach-api.yaml?
  • Is there something I should do in toc.json to suggest this grouping of endpoints?