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.

Sidebar navigation

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.

unified:
  - page: openapi/rock.page.yaml
  - page: openapi/paper.page.yaml
  - page: openapi/scissors.page.yaml

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.

rock:
  - page: openapi/rock.page.yaml
paper:
  - page: openapi/paper.page.yaml
scissors:
  - page: openapi/scissors.page.yaml/*

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.

drilldown-style:
  - group: Rock
    menuStyle: drilldown
    pages:
      - page: openapi/rock.page.yaml/*
  - group: Paper
    menuStyle: drilldown
    pages:
      - page: openapi/paper.page.yaml/*
  - group: Scissors
    menuStyle: drilldown
    pages:
      - page: openapi/scissors.page.yaml/*

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/rock.page.yaml" 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>
    <ThinTile to="openapi/paper.page.yaml" icon={paper} header="Paper">
        The Paper API frightens the Rock API.
    </ThinTile>
    <ThinTile to="openapi/scissors.page.yaml" icon={scissors} header="Scissors">
        The Scissors API is great as long as it stays away from the Rock API.
    </ThinTile>
  </FlexSection>

Search

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.