paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 26 Packages Projects Releases Wiki Activity

docs(api-docs): update README for new frontend system as default

Browse Source 
Add new frontend system installation as the default path with package
discovery. Move old frontend system wiring to an "Old Frontend System"
section. Update README-alpha.md to be an extension reference rather
than experimental documentation.

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
Made-with: Cursor
This commit is contained in:
Patrik Oldsberg
2026-03-04 11:38:40 +01:00
parent 96662b763e
commit ae71853b45
2 changed files with 88 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plugins/api-docs/README.md
+86 -65
View File
@@ -1,8 +1,5 @@
# API Documentation
> Disclaimer:
> If you are looking for documentation on the experimental new frontend system support, please go [here](./README-alpha.md).
This is an extension for the catalog plugin that provides components to discover and display API entities.
APIs define the interface between components, see the [system model](https://backstage.io/docs/features/software-catalog/system-model) for details.
They are defined in machine readable formats and provide a human readable documentation.
@@ -28,77 +25,32 @@ To link that a component provides or consumes an API, see the [`providesApis`](h
> The plugin is already added when using `npx @backstage/create-app` so you can skip these steps.
1. Install the API docs plugin
```bash
# From your Backstage root directory
yarn --cwd packages/app add @backstage/plugin-api-docs
```
2. Add the `ApiExplorerPage` extension to the app:
Once installed, the plugin is automatically available in your app through the default package discovery. For more details and alternative installation methods, see [installing plugins](https://backstage.io/docs/frontend-system/building-apps/installing-plugins).
```tsx
// In packages/app/src/App.tsx
You can enable entity cards and tabs on the catalog entity page through configuration:
import { ApiExplorerPage } from '@backstage/plugin-api-docs';
<Route path="/api-docs" element={<ApiExplorerPage />} />;
```yaml
# app-config.yaml
app:
extensions:
- entity-card:api-docs/providing-components:
config:
filter:
kind: api
- entity-card:api-docs/consuming-components:
config:
filter:
kind: api
- entity-content:api-docs/definition
- entity-content:api-docs/apis
```
3. Add one of the provided widgets to the EntityPage:
```tsx
// 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 xs={12} md={6}>
<EntityAboutCard />
</Grid>
<Grid container>
<Grid item md={12}>
<Grid item xs={12} md={6}>
<EntityProvidingComponentsCard />
</Grid>
<Grid item xs={12} md={6}>
<EntityConsumingComponentsCard />
</Grid>
</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>
);
```
There are other components to discover in [`./src/components`](./src/components) that are also added by the default app.
For the full list of available extensions and their configuration options, see the [README-alpha.md](./README-alpha.md).
## Customizations
@@ -388,6 +340,75 @@ import { ApiExplorerPage } from '@backstage/plugin-api-docs';
/>;
```
## Old Frontend System
If your Backstage app uses the old frontend system, you need to manually wire the plugin into your app.
1. Add the `ApiExplorerPage` extension to the app:
```tsx
// In packages/app/src/App.tsx
import { ApiExplorerPage } from '@backstage/plugin-api-docs';
<Route path="/api-docs" element={<ApiExplorerPage />} />;
```
2. Add one of the provided widgets to the EntityPage:
```tsx
// 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 xs={12} md={6}>
<EntityAboutCard />
</Grid>
<Grid container>
<Grid item md={12}>
<Grid item xs={12} md={6}>
<EntityProvidingComponentsCard />
</Grid>
<Grid item xs={12} md={6}>
<EntityConsumingComponentsCard />
</Grid>
</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>
);
```
There are other components to discover in [`./src/components`](./src/components) that are also added by the default app.
## Links
- [The Backstage homepage](https://backstage.io)