Backstage API Docs Plugin

If you're a Backstage developer, chances are you're managing a growing number of APIs across services, teams, and domains. The Backstage API Docs plugin turns your catalog of API specs into a first‐class, discoverable resource—making it easier for engineers to find, understand, and consume internal APIs. Instead of hunting through repos, dashboards, or external docs, your OpenAPI, AsyncAPI, or GraphQL specs are visible directly in Backstage alongside components, ownership, and lifecycle metadata.

By embedding API specs within Backstage, you gain:

• Faster discovery: APIs show up as entities in the catalog, including search, filters, tags, and relationships (which service provides or uses which API).
• Better alignment: Teams can see the spec of each API, and understand versioning or lifecycle without duplicating effort.
• Improved onboarding & documentation consistency: New engineers can navigate your API landscape clearly via rendered specs (OpenAPI/AsyncAPI/GraphQL), complete with links from component pages. Spec definitions can live next to code or be imported through catalog entity files.

This plugin is already part of many Backstage setups (including when using npx @backstage/create-app), but you can also add it to an existing Backstage instance by installing @backstage/plugin-api-docs. Once installed, you get UI components for browsing API specs (e.g. via an ApiExplorerPage) and cards in your Entity pages (API definition, consuming/providing services, etc.).

Below you’ll find how to install, configure, and manage the API Docs plugin—how to connect spec sources, customize rendering, and ensure developers in your organisation can reliably discover, trust, and use your APIs rather than inventing new ones.

yarn add @backstage/plugin-api-docs

// In packages/app/src/App.tsx
import { ApiExplorerPage } from '@backstage/plugin-api-docs';
<Route path="/api-docs" element={<ApiExplorerPage />} />;

// packages/app/src/components/catalog/EntityPage.tsx

import {
  EntityAboutCard,
  EntityApiDefinitionCard,
  EntityConsumingComponentsCard,
  EntityProvidingComponentsCard,
} from '@backstage/plugin-api-docs';


const apiPage = (
  <EntityLayout>
    ...
    <EntityLayout.Route path="/" title="Overview">
      <Grid container spacing={3}>
        <Grid item md={6}>
          <EntityAboutCard />
        </Grid>
        <Grid container item md={12}>
          <Grid item md={6}>
            <EntityProvidingComponentsCard />
          </Grid>
          <Grid item md={6}>
            <EntityConsumingComponentsCard />
          </Grid>
        </Grid>
      </Grid>
    </EntityLayout.Route>

    <EntityLayout.Route path="/definition" title="Definition">
      <Grid container spacing={3}>
        <Grid item xs={12}>
          <EntityApiDefinitionCard />
        </Grid>
      </Grid>
    </EntityLayout.Route>
  </EntityLayout>
);

// ...

export const entityPage = (
  <EntitySwitch>
    // ...
    <EntitySwitch.Case if={isKind('api')} children={apiPage} />
    // ...
  </EntitySwitch>
);