Merge pull request #2088 from andrewthauer/api-docs-graphql

Add GraphQL support to API Docs

docs/features/software-catalog/descriptor-format.md

@@ -471,6 +471,7 @@ Describes the following entity kind:
 An API describes an interface that can be exposed by a component. The API can be
 defined in different formats, like [OpenAPI](https://swagger.io/specification/),
 [AsyncAPI](https://www.asyncapi.com/docs/specifications/latest/),
+[GraphQL](https://graphql.org/learn/schema/),
 [gRPC](https://developers.google.com/protocol-buffers), or other formats.
 
 Descriptor files for this kind may look as follows.

plugins/api-docs/README.md

@@ -14,8 +14,9 @@ The plugin provides a standalone list of APIs, as well as an integration into th
 
 Right now, the following API formats are supported:
 
-- [OpenAPI](https://swagger.io/specification/) 2 & 3,
-- [AsyncAPI](https://www.asyncapi.com/docs/specifications/latest/),
+- [OpenAPI](https://swagger.io/specification/) 2 & 3
+- [AsyncAPI](https://www.asyncapi.com/docs/specifications/latest/)
+- [GraphQL](https://graphql.org/learn/schema/)
 
 Other formats are displayed as plain text, but this can easily be extented.
 

plugins/api-docs/package.json

@@ -29,6 +29,8 @@
     "@material-ui/core": "^4.11.0",
     "@material-ui/icons": "^4.9.1",
     "@material-ui/lab": "4.0.0-alpha.45",
+    "graphiql": "^1.0.0-alpha.10",
+    "graphql": "^15.3.0",
     "react": "^16.13.1",
     "react-dom": "^16.13.1",
     "react-router": "6.0.0-beta.0",

plugins/api-docs/src/catalog/EntityPageApi/EntityPageApi.tsx

@@ -16,7 +16,7 @@
 
 import { ComponentEntity, Entity } from '@backstage/catalog-model';
 import { Progress } from '@backstage/core';
-import React, { FC } from 'react';
+import React from 'react';
 import { Grid } from '@material-ui/core';
 import {
   ApiDefinitionCard,
@@ -24,7 +24,11 @@ import {
   useComponentApiNames,
 } from '../../components';
 
-export const EntityPageApi: FC<{ entity: Entity }> = ({ entity }) => {
+type Props = {
+  entity: Entity;
+};
+
+export const EntityPageApi = ({ entity }: Props) => {
   const apiNames = useComponentApiNames(entity as ComponentEntity);
 
   const { apiEntities, loading } = useComponentApiEntities({

plugins/api-docs/src/components/ApiDefinitionCard/ApiDefinitionCard.tsx

@@ -15,12 +15,13 @@
  */
 
 import { ApiEntity } from '@backstage/catalog-model';
-import { TabbedCard, CardTab } from '@backstage/core';
+import { CardTab, TabbedCard } from '@backstage/core';
+import { Alert } from '@material-ui/lab';
 import React from 'react';
 import { PlainApiDefinitionWidget } from '../PlainApiDefinitionWidget';
-import { Alert } from '@material-ui/lab';
 import { OpenApiDefinitionWidget } from '../OpenApiDefinitionWidget';
 import { AsyncApiDefinitionWidget } from '../AsyncApiDefinitionWidget';
+import { GraphQlDefinitionWidget } from '../GraphQlDefinitionWidget';
 
 type ApiDefinitionWidget = {
   type: string;
@@ -47,6 +48,14 @@ export function defaultDefinitionWidgets(): ApiDefinitionWidget[] {
         <AsyncApiDefinitionWidget definition={definition} />
       ),
     },
+    {
+      type: 'graphql',
+      title: 'GraphQL',
+      rawLanguage: 'graphql',
+      component: definition => (
+        <GraphQlDefinitionWidget definition={definition} />
+      ),
+    },
   ];
 }
 

plugins/api-docs/src/components/ApiEntityPage/ApiEntityPage.tsx

@@ -34,6 +34,7 @@ import { useAsync } from 'react-use';
 import { ApiDefinitionCard } from '../ApiDefinitionCard';
 
 const REDIRECT_DELAY = 1000;
+
 function headerProps(
   kind: string,
   namespace: string | undefined,

plugins/api-docs/src/components/GraphQlDefinitionWidget/GraphQlDefinitionWidget.tsx

@@ -0,0 +1,66 @@
+/*
+ * 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, { Suspense } from 'react';
+import { buildSchema } from 'graphql';
+import { makeStyles } from '@material-ui/core/styles';
+import { Progress } from '@backstage/core';
+import { BackstageTheme } from '@backstage/theme';
+
+const GraphiQL = React.lazy(() => import('graphiql'));
+
+const useStyles = makeStyles<BackstageTheme>(() => ({
+  root: {
+    height: '100%',
+    display: 'flex',
+    flexFlow: 'column nowrap',
+  },
+  graphiQlWrapper: {
+    flex: 1,
+    '@global': {
+      '.graphiql-container': {
+        boxSizing: 'initial',
+        height: '100%',
+        minHeight: '600px',
+        flex: '1 1 auto',
+      },
+    },
+  },
+}));
+
+type Props = {
+  definition: any;
+};
+
+export const GraphQlDefinitionWidget = ({ definition }: Props) => {
+  const classes = useStyles();
+  const schema = buildSchema(definition);
+
+  return (
+    <Suspense fallback={<Progress />}>
+      <div className={classes.root}>
+        <div className={classes.graphiQlWrapper}>
+          <GraphiQL
+            fetcher={() => Promise.resolve(null) as any}
+            schema={schema}
+            docExplorerOpen
+            defaultSecondaryEditorOpen={false}
+          />
+        </div>
+      </div>
+    </Suspense>
+  );
+};

plugins/api-docs/src/components/GraphQlDefinitionWidget/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 { GraphQlDefinitionWidget } from './GraphQlDefinitionWidget';