Document how to customize the API docs rendering

Signed-off-by: Dominik Henneke <dominik.henneke@sda-se.com>
2021-04-08 18:02:07 +02:00
parent f240b09965
commit d17b39d04e
4 changed files with 140 additions and 6 deletions
@@ -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: