From 2e1a0b8c99afa8557078afc8ab7102430513e6f7 Mon Sep 17 00:00:00 2001
From: Dominik Henneke <dominik.henneke@sda-se.com>
Date: Fri, 16 Oct 2020 16:02:08 +0200
Subject: [PATCH] feat(api-docs): show a custom error page when no apis are
 implemented by a component (#2933)

---
 .../MissingImplementsApisEmptyState.tsx       | 82 +++++++++++++++++++
 .../MissingImplementsApisEmptyState/index.ts  | 17 ++++
 plugins/api-docs/src/catalog/Router.tsx       |  7 +-
 3 files changed, 101 insertions(+), 5 deletions(-)
 create mode 100644 plugins/api-docs/src/catalog/MissingImplementsApisEmptyState/MissingImplementsApisEmptyState.tsx
 create mode 100644 plugins/api-docs/src/catalog/MissingImplementsApisEmptyState/index.ts

diff --git a/plugins/api-docs/src/catalog/MissingImplementsApisEmptyState/MissingImplementsApisEmptyState.tsx b/plugins/api-docs/src/catalog/MissingImplementsApisEmptyState/MissingImplementsApisEmptyState.tsx
new file mode 100644
index 0000000000..9160aca514
--- /dev/null
+++ b/plugins/api-docs/src/catalog/MissingImplementsApisEmptyState/MissingImplementsApisEmptyState.tsx
@@ -0,0 +1,82 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * 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 { Button, makeStyles, Typography } from '@material-ui/core';
+import { BackstageTheme } from '@backstage/theme';
+import { CodeSnippet, EmptyState } from '@backstage/core';
+
+const COMPONENT_YAML = `# Example
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: example
+spec:
+  type: service
+  lifecycle: production
+  owner: guest
+  implementsApis:
+    - example-api
+`;
+
+const useStyles = makeStyles<BackstageTheme>(theme => ({
+  code: {
+    borderRadius: 6,
+    margin: `${theme.spacing(2)}px 0px`,
+    background: theme.palette.type === 'dark' ? '#444' : '#fff',
+  },
+}));
+
+export const MissingImplementsApisEmptyState = () => {
+  const classes = useStyles();
+  return (
+    <EmptyState
+      missing="field"
+      title="No APIs implemented by this entity"
+      description={
+        <Typography>
+          Components can implement APIs that are displayed on this page. You
+          need to fill the <code>implementsApis</code> field to enable this
+          tool.
+        </Typography>
+      }
+      action={
+        <>
+          <Typography variant="body1">
+            Link an API to your component as shown in the highlighted example
+            below:
+          </Typography>
+          <div className={classes.code}>
+            <CodeSnippet
+              text={COMPONENT_YAML}
+              language="yaml"
+              showLineNumbers
+              highlightedNumbers={[10, 11]}
+              customStyle={{ background: 'inherit', fontSize: '115%' }}
+            />
+          </div>
+          <Button
+            variant="contained"
+            color="primary"
+            href="https://backstage.io/docs/features/software-catalog/descriptor-format#specimplementsapis-optional"
+          >
+            Read more
+          </Button>
+        </>
+      }
+    />
+  );
+};
diff --git a/plugins/api-docs/src/catalog/MissingImplementsApisEmptyState/index.ts b/plugins/api-docs/src/catalog/MissingImplementsApisEmptyState/index.ts
new file mode 100644
index 0000000000..1b7d35c0a2
--- /dev/null
+++ b/plugins/api-docs/src/catalog/MissingImplementsApisEmptyState/index.ts
@@ -0,0 +1,17 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * 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.
+ */
+
+export { MissingImplementsApisEmptyState } from './MissingImplementsApisEmptyState';
diff --git a/plugins/api-docs/src/catalog/Router.tsx b/plugins/api-docs/src/catalog/Router.tsx
index 71640954b3..d3fe7f7553 100644
--- a/plugins/api-docs/src/catalog/Router.tsx
+++ b/plugins/api-docs/src/catalog/Router.tsx
@@ -17,20 +17,17 @@
 import React from 'react';
 import { Entity } from '@backstage/catalog-model';
 import { Route, Routes } from 'react-router';
-import { WarningPanel } from '@backstage/core';
 import { catalogRoute } from '../routes';
 import { EntityPageApi } from './EntityPageApi';
+import { MissingImplementsApisEmptyState } from './MissingImplementsApisEmptyState';
 
 const isPluginApplicableToEntity = (entity: Entity) => {
   return ((entity.spec?.implementsApis as string[]) || []).length > 0;
 };
 
 export const Router = ({ entity }: { entity: Entity }) =>
-  // TODO(shmidt-i): move warning to a separate standardized component
   !isPluginApplicableToEntity(entity) ? (
-    <WarningPanel title="API Docs plugin:">
-      The entity doesn't implement any APIs.
-    </WarningPanel>
+    <MissingImplementsApisEmptyState />
   ) : (
     <Routes>
       <Route