As a developer wanting to understand an API

Given I want to have an overview of all API endpoints / operations related to specific subject, theme, concept, entity, etc

Then I want to be able to filter API endpoints by tags, or referenced resources

Details

Currently, when navigating an API reference documentation, three navigation flows are possible:

• Scrolling through endpoints

• Choosing a section from the left sidebar navigation menu and going to it(which scrolls the main view to that section)

• searching for a term and clicking on one of the result, which scrolls the main view to that entry

This works for browsing endpoints and finding a specific endpoint.

However this does not work if one wants a filtered view of all endpoints relating to some term, or associated with some tag.

In some cases, endpoints relative to such a scope are in the same section, but often relevant endpoints are spread across many sections(multiple sub-API namespaces).

A good example is the wazo-dird API, which has endpoints such as /phonebooks/* but also /backends/phonebook/*, which are logically connected.

I can see two complementary approaches that would be useful:

• filtering by tags present on path operations

• filtering based on search terms(like current search, but show matching results of search in main view)