Merge pull request #22752 from backstage/camilaibs/migrate-api-docs-plugin-to-new-system

Migrate api docs plugin to new system

plugins/api-docs/README.md

@@ -1,5 +1,8 @@
 # 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.

plugins/api-docs/api-report-alpha.md

@@ -0,0 +1,22 @@
+## API Report File for "@backstage/plugin-api-docs"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+import { BackstagePlugin } from '@backstage/frontend-plugin-api';
+import { ExternalRouteRef } from '@backstage/frontend-plugin-api';
+import { RouteRef } from '@backstage/frontend-plugin-api';
+
+// @public (undocumented)
+const _default: BackstagePlugin<
+  {
+    root: RouteRef<undefined>;
+  },
+  {
+    registerApi: ExternalRouteRef<undefined, true>;
+  }
+>;
+export default _default;
+
+// (No @packageDocumentation comment for this package)
+```

plugins/api-docs/package.json

@@ -6,9 +6,22 @@
   "types": "src/index.ts",
   "license": "Apache-2.0",
   "publishConfig": {
-    "access": "public",
-    "main": "dist/index.esm.js",
-    "types": "dist/index.d.ts"
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./alpha": "./src/alpha.tsx",
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "alpha": [
+        "src/alpha.tsx"
+      ],
+      "package.json": [
+        "package.json"
+      ]
+    }
   },
   "backstage": {
     "role": "frontend-plugin"
@@ -35,8 +48,10 @@
   "dependencies": {
     "@asyncapi/react-component": "1.2.13",
     "@backstage/catalog-model": "workspace:^",
+    "@backstage/core-compat-api": "workspace:^",
     "@backstage/core-components": "workspace:^",
     "@backstage/core-plugin-api": "workspace:^",
+    "@backstage/frontend-plugin-api": "workspace:^",
     "@backstage/plugin-catalog": "workspace:^",
     "@backstage/plugin-catalog-common": "workspace:^",
     "@backstage/plugin-catalog-react": "workspace:^",

plugins/api-docs/src/alpha.tsx

@@ -0,0 +1,233 @@
+/*
+ * Copyright 2024 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import React from 'react';
+import { Grid } from '@material-ui/core';
+
+import {
+  createApiExtension,
+  createApiFactory,
+  createNavItemExtension,
+  createPageExtension,
+  createPlugin,
+  createSchemaFromZod,
+} from '@backstage/frontend-plugin-api';
+
+import {
+  compatWrapper,
+  convertLegacyRouteRef,
+} from '@backstage/core-compat-api';
+import { useApp } from '@backstage/core-plugin-api';
+
+import {
+  createEntityCardExtension,
+  createEntityContentExtension,
+} from '@backstage/plugin-catalog-react/alpha';
+import {
+  ApiEntity,
+  parseEntityRef,
+  RELATION_HAS_PART,
+} from '@backstage/catalog-model';
+
+import { defaultDefinitionWidgets } from './components/ApiDefinitionCard';
+import { rootRoute, registerComponentRouteRef } from './routes';
+import { apiDocsConfigRef } from './config';
+
+function ApiIcon() {
+  const app = useApp();
+  const KindApiSystemIcon = app.getSystemIcon('kind:api')!;
+  return <KindApiSystemIcon />;
+}
+
+const apiDocsNavItem = createNavItemExtension({
+  title: 'APIs',
+  routeRef: convertLegacyRouteRef(rootRoute),
+  icon: () => compatWrapper(<ApiIcon />),
+});
+
+const apiDocsConfigApi = createApiExtension({
+  factory: createApiFactory({
+    api: apiDocsConfigRef,
+    deps: {},
+    factory: () => {
+      const definitionWidgets = defaultDefinitionWidgets();
+      return {
+        getApiDefinitionWidget: (apiEntity: ApiEntity) => {
+          return definitionWidgets.find(d => d.type === apiEntity.spec.type);
+        },
+      };
+    },
+  }),
+});
+
+const apiDocsExplorerPage = createPageExtension({
+  defaultPath: '/api-docs',
+  routeRef: convertLegacyRouteRef(rootRoute),
+  // Mapping DefaultApiExplorerPageProps to config
+  configSchema: createSchemaFromZod(z =>
+    z.object({
+      path: z.string().default('/api-docs'),
+      initiallySelectedFilter: z.enum(['owned', 'starred', 'all']).optional(),
+      // Ommiting columns and actions for now as their types are too complex to map to zod
+    }),
+  ),
+  loader: ({ config }) =>
+    import('./components/ApiExplorerPage').then(m =>
+      compatWrapper(
+        <m.ApiExplorerIndexPage
+          initiallySelectedFilter={config.initiallySelectedFilter}
+        />,
+      ),
+    ),
+});
+
+const apiDocsHasApisEntityCard = createEntityCardExtension({
+  name: 'has-apis',
+  // Ommiting configSchema for now
+  // We are skipping variants and columns are too complex to map to zod
+  // See: https://github.com/backstage/backstage/pull/22619#discussion_r1477333252
+  filter: entity => {
+    return (
+      entity.kind === 'Component' &&
+      entity.relations?.some(
+        ({ type, targetRef }) =>
+          type.toLocaleLowerCase('en-US') === RELATION_HAS_PART &&
+          parseEntityRef(targetRef).kind === 'API',
+      )!!
+    );
+  },
+  loader: () =>
+    import('./components/ApisCards').then(m =>
+      compatWrapper(<m.HasApisCard />),
+    ),
+});
+
+const apiDocsDefinitionEntityCard = createEntityCardExtension({
+  name: 'definition',
+  filter: 'kind:api',
+  loader: () =>
+    import('./components/ApiDefinitionCard').then(m =>
+      compatWrapper(<m.ApiDefinitionCard />),
+    ),
+});
+
+const apiDocsConsumedApisEntityCard = createEntityCardExtension({
+  name: 'consumed-apis',
+  // Ommiting configSchema for now
+  // We are skipping variants and columns are too complex to map to zod
+  // See: https://github.com/backstage/backstage/pull/22619#discussion_r1477333252
+  filter: 'kind:component',
+  loader: () =>
+    import('./components/ApisCards').then(m =>
+      compatWrapper(<m.ConsumedApisCard />),
+    ),
+});
+
+const apiDocsProvidedApisEntityCard = createEntityCardExtension({
+  name: 'provided-apis',
+  // Ommiting configSchema for now
+  // We are skipping variants and columns are too complex to map to zod
+  // See: https://github.com/backstage/backstage/pull/22619#discussion_r1477333252
+  filter: 'kind:component',
+  loader: () =>
+    import('./components/ApisCards').then(m =>
+      compatWrapper(<m.ProvidedApisCard />),
+    ),
+});
+
+const apiDocsConsumingComponentsEntityCard = createEntityCardExtension({
+  name: 'consuming-components',
+  // Ommiting configSchema for now
+  // We are skipping variants
+  // See: https://github.com/backstage/backstage/pull/22619#discussion_r1477333252
+  filter: 'kind:api',
+  loader: () =>
+    import('./components/ComponentsCards').then(m =>
+      compatWrapper(<m.ConsumingComponentsCard />),
+    ),
+});
+
+const apiDocsProvidingComponentsEntityCard = createEntityCardExtension({
+  name: 'providing-components',
+  // Ommiting configSchema for now
+  // We are skipping variants
+  // See: https://github.com/backstage/backstage/pull/22619#discussion_r1477333252
+  filter: 'kind:api',
+  loader: () =>
+    import('./components/ComponentsCards').then(m =>
+      compatWrapper(<m.ProvidingComponentsCard />),
+    ),
+});
+
+const apiDocsDefinitionEntityContent = createEntityContentExtension({
+  name: 'definition',
+  defaultPath: '/defintion',
+  defaultTitle: 'Definition',
+  filter: 'kind:api',
+  loader: async () =>
+    import('./components/ApiDefinitionCard').then(m =>
+      compatWrapper(
+        <Grid container spacing={3}>
+          <Grid item xs={12}>
+            <m.ApiDefinitionCard />
+          </Grid>
+        </Grid>,
+      ),
+    ),
+});
+
+const apiDocsApisEntityContent = createEntityContentExtension({
+  name: 'apis',
+  defaultPath: '/apis',
+  defaultTitle: 'APIs',
+  filter: 'kind:component',
+  loader: async () =>
+    import('./components/ApisCards').then(m =>
+      compatWrapper(
+        <Grid container spacing={3} alignItems="stretch">
+          <Grid item xs={12}>
+            <m.ProvidedApisCard />
+          </Grid>
+          <Grid item xs={12}>
+            <m.ConsumedApisCard />
+          </Grid>
+        </Grid>,
+      ),
+    ),
+});
+
+export default createPlugin({
+  id: 'api-docs',
+  routes: {
+    root: convertLegacyRouteRef(rootRoute),
+  },
+  externalRoutes: {
+    registerApi: convertLegacyRouteRef(registerComponentRouteRef),
+  },
+  extensions: [
+    apiDocsNavItem,
+    apiDocsConfigApi,
+    apiDocsExplorerPage,
+    apiDocsHasApisEntityCard,
+    apiDocsDefinitionEntityCard,
+    apiDocsProvidedApisEntityCard,
+    apiDocsConsumedApisEntityCard,
+    apiDocsConsumingComponentsEntityCard,
+    apiDocsProvidingComponentsEntityCard,
+    apiDocsDefinitionEntityContent,
+    apiDocsApisEntityContent,
+  ],
+});