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

Document how to customize the API docs rendering

Browse Source 
Signed-off-by: Dominik Henneke <dominik.henneke@sda-se.com>
This commit is contained in:
Dominik Henneke
2021-04-08 18:02:07 +02:00
parent f240b09965
commit d17b39d04e
4 changed files with 140 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plugins/api-docs/README.md
+140 -6
View File
@@ -1,7 +1,5 @@
# API Documentation
WORK IN PROGRESS
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.
@@ -23,9 +21,145 @@ Other formats are displayed as plain text, but this can easily be extended.
To fill the catalog with APIs, [provide entities of kind API](https://backstage.io/docs/features/software-catalog/descriptor-format#kind-api).
To link that a component provides or consumes an API, see the [`providesApis`](https://backstage.io/docs/features/software-catalog/descriptor-format#specprovidesapis-optional) and [`consumesApis`](https://backstage.io/docs/features/software-catalog/descriptor-format#specconsumesapis-optional) properties on the Component kind.
## Implementing OAuth 2 Authorization Code flow with Swagger UI
## Getting Started
### Adding `oauth2-redirect.html` to support OAuth2 `redirect_uri` route
> The plugin is already added when using `npx @backstage/create-app` so you can skip these steps.
1. Install the API docs plugin
```bash
# packages/app
yarn add @backstage/plugin-api-docs
```
2. Add the plugin to the app:
```ts
// packages/app/src/plugins.ts
export { apiDocsPlugin } from '@backstage/plugin-api-docs';
```
<Route path="/api-docs" element={<ApiExplorerPage />} />
3. Register the `ApiExplorerPage` at the `/api-docs` path:
```tsx
// packages/app/src/App.tsx
import { ApiExplorerPage } from '@backstage/plugin-api-docs';
<Route path="/api-docs" element={<ApiExplorerPage />} />;
```
4. 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 = (
<EntityLayoutWrapper>
<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>
</EntityLayoutWrapper>
);
// ...
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.
## Customizations
### Custom API Renderings
You can add support for additional API types by providing a custom implementation for the `apiDocsConfigRef`.
You can also use this to override the rendering of one of the already supported types.
This is an example with a made-up renderer for SQL schemas:
```tsx
// packages/app/src/apis.tsx
import { ApiEntity } from '@backstage/catalog-model';
import {
ApiDefinitionWidget,
apiDocsConfigRef,
defaultDefinitionWidgets,
} from '@backstage/plugin-api-docs';
import { SqlRenderer } from '...';
// ...
export const apis: AnyApiFactory[] = [
// ...
createApiFactory({
api: apiDocsConfigRef,
deps: {},
factory: () => {
// load the default widgets
const definitionWidgets = defaultDefinitionWidgets();
return {
getApiDefinitionWidget: (apiEntity: ApiEntity) => {
// custom rendering for sql
if (apiEntity.spec.type === 'sql') {
return {
type: 'sql',
title: 'SQL',
component: definition => <SqlRenderer definition={definition} />,
} as ApiDefinitionWidget;
}
// fallback to the defaults
return definitionWidgets.find(d => d.type === apiEntity.spec.type);
},
};
},
}),
];
```
### Implementing OAuth 2 Authorization Code flow with Swagger UI
#### Adding `oauth2-redirect.html` to support OAuth2 `redirect_uri` route
The Swagger UI package by expects to have a route to `/oauth2-redirect.html` which processes
the redirect callback for the OAuth2 Authorization Code flow, however, this file is not installed
@@ -34,7 +168,7 @@ by this plugin.
Grab a copy of [oauth2-redirect.html](https://github.com/swagger-api/swagger-ui/blob/master/dist/oauth2-redirect.html)
and put it in the `app/public/` directory in order to enable Swagger UI to complete this redirection.
### Configuring your OAuth2 Client
#### Configuring your OAuth2 Client
You'll need to make sure your OAuth2 client has been registered in your OAuth2 Authentication Server (AS)
with the appropriate `redirect_uris`, `scopes` and `grant_types`. For example, if your AS supports
@@ -62,7 +196,7 @@ The above `redirect_uris` are:
- Local Backstage app development: `http://localhost:3000/oauth2-redirect.html`
- Backstage app production: `https://<yourhost>/oauth2-redirect.html`
### Configuring OAuth2 in your OpenAPI 3.0 schema
#### Configuring OAuth2 in your OpenAPI 3.0 schema
To configure [OAuth 2 Authorization Code](https://swagger.io/docs/specification/authentication/oauth2/) flow
in your OpenAPI 3.0 schema you'll need something like this snippet: