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

Merge pull request #33113 from backstage/rugvip/docs-frontend-plugin-installation

Browse Source 
docs: default frontend plugin docs to the new frontend system
This commit is contained in:
Patrik Oldsberg
2026-03-16 22:08:47 +01:00
committed by GitHub
parent 22f101e208 1decc6f994
commit 55b18a3c2e
22 changed files with 722 additions and 614 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plugins/api-docs/README-alpha.md
+2 -4
View File
@@ -1,8 +1,6 @@
# Api Docs
# Api Docs - Extension Reference
> [!WARNING]
> This documentation is made for those using the experimental new Frontend system.
> If you are not using the new frontend system, please go [here](./README.md).
This page contains detailed documentation for all extensions provided by the `@backstage/plugin-api-docs` plugin. For general information about the plugin, see the [README](./README.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.
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 feature 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 as outlined in this section. If you are on the new frontend system, you can skip this.
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)