diff --git a/plugins/api-docs/README.md b/plugins/api-docs/README.md
index 0b8d658f89..4e71e87275 100644
--- a/plugins/api-docs/README.md
+++ b/plugins/api-docs/README.md
@@ -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';
+```
+
+} />
+
+3. Register the `ApiExplorerPage` at the `/api-docs` path:
+
+```tsx
+// packages/app/src/App.tsx
+
+import { ApiExplorerPage } from '@backstage/plugin-api-docs';
+
+} />;
+```
+
+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 = (
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+);
+
+// ...
+
+export const entityPage = (
+
+ // ...
+
+ // ...
+
+);
+```
+
+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 => ,
+ } 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:///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:
diff --git a/plugins/api-docs/docs/api_list.png b/plugins/api-docs/docs/api_list.png
index 4ca2f09542..97d38e25a6 100644
Binary files a/plugins/api-docs/docs/api_list.png and b/plugins/api-docs/docs/api_list.png differ
diff --git a/plugins/api-docs/docs/entity_tab_api.png b/plugins/api-docs/docs/entity_tab_api.png
index 439fac73fa..213f6eb04a 100644
Binary files a/plugins/api-docs/docs/entity_tab_api.png and b/plugins/api-docs/docs/entity_tab_api.png differ
diff --git a/plugins/api-docs/docs/openapi_definition.png b/plugins/api-docs/docs/openapi_definition.png
index 49d12a08e8..c6a0350914 100644
Binary files a/plugins/api-docs/docs/openapi_definition.png and b/plugins/api-docs/docs/openapi_definition.png differ