Does your organization own documentation for multiple APIs?

How can users find them? This topic is commonly called API discovery.

Let's pretend your organization has three APIs: rock, paper, and scissors.

They are each maintained by separate teams following the microservices approach.

Redocly supports a few options for presenting the sidebar (which typically appears as the left navigation) to users.

Unified sidebar

A unified sidebar approach would show all of the APIs in a single sidebar.

  - page: openapi/
  - page: openapi/
  - page: openapi/


Different sidebars

When someone navigates to the API, they would land on this page.

Here is a snippet from the sidebars.yaml that shows three different sidebars defined.

  - page: openapi/
  - page: openapi/
  - page: openapi/*

The sidebar will be contextual to the API.

For example, when visiting the Paper API, it is the only API displayed in the sidebar.


The /* at the end of the scissors sidebar showcases a different behavior by removing the initial group with the API name. Here is an example:


Drilldown sidebar

The drilldown sidebar allows the user to see the top level API catalog in the sidebar. When they click on an API product, they drill down deeper into the sidebar. This behavior is similar to a hybrid between the unified and different sidebars. In the drilldown behavior, the sidebar only shows the appropriate segment of navigation, with a back link to return to the parent sidebar.

  - group: Rock
    menuStyle: drilldown
      - page: openapi/*
  - group: Paper
    menuStyle: drilldown
      - page: openapi/*
  - group: Scissors
    menuStyle: drilldown
      - page: openapi/*


See the example pull request for more details.

API catalog

You may want to showcase your API catalog on a landing page. One common idea is to use a tile to represent each product in the API catalog.

  <FlexSection justifyContent="space-around" flexWrap="wrap">
    <ThinTile to="openapi/" icon={rock} header="Rock">
        This is the Rock API. It thinks it is better than the Scissors API. But it has to watch out for paper.
    <ThinTile to="openapi/" icon={paper} header="Paper">
        The Paper API frightens the Rock API.
    <ThinTile to="openapi/" icon={scissors} header="Scissors">
        The Scissors API is great as long as it stays away from the Rock API.


Another popular method of API discovery is a search feature.

You can enable search for your Redocly Developer portal in the siteConfig.yaml within the nav section:

  - search: true

How will you organize your APIs to make them discoverable by your consumers? Do you have a different approach you want to see us support? Let us know.

Latest from our blog

Ensure consistent APIs with Redocly and ...

Put some magic API tools in your continuous integration and make a good API grow up to be a great API.

Getting started with API governance

Take your first steps to better APIs with our approachable guide to getting started with API governance.

Making metrics at WriteTheDocs Portland ...

Learn about the importance in using research and metrics in creating value for readers and demonstrating value as writers, as well as some highlights from the talks.