Merge pull request #5532 from SDA-SE/feat/json-schmea

Add support for json schema to API docs

.changeset/six-mayflies-peel.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-api-docs': patch
+---
+
+Add support for displaying JSON schemas.

packages/catalog-model/examples/all-apis.yaml

@@ -5,6 +5,7 @@ metadata:
   description: A collection of all Backstage example APIs
 spec:
   targets:
+    - ./apis/config-schema-api.yaml
     - ./apis/hello-world-api.yaml
     - ./apis/petstore-api.yaml
     - ./apis/spotify-api.yaml

packages/catalog-model/examples/apis/config-schema-api.yaml

@@ -0,0 +1,11 @@
+apiVersion: backstage.io/v1alpha1
+kind: API
+metadata:
+  name: config-schema
+  description: A Backstage config schemas.
+spec:
+  type: jsonschema
+  lifecycle: production
+  owner: team-a
+  definition:
+    $text: https://github.com/backstage/backstage/blob/master/plugins/config-schema/dev/example-schema.json

plugins/api-docs/README.md

@@ -15,6 +15,7 @@ Right now, the following API formats are supported:
 - [OpenAPI](https://swagger.io/specification/) 2 & 3
 - [AsyncAPI](https://www.asyncapi.com/docs/specifications/latest/)
 - [GraphQL](https://graphql.org/learn/schema/)
+- [JSON Schema](https://json-schema.org/)
 
 Other formats are displayed as plain text, but this can easily be extended.
 

plugins/api-docs/dev/index.tsx

@@ -27,6 +27,7 @@ import {
 } from '../src';
 import asyncapiApiEntity from './asyncapi-example-api.yaml';
 import graphqlApiEntity from './graphql-example-api.yaml';
+import jsonschemaApiEntity from './jsonschema-example-api.yaml';
 import openapiApiEntity from './openapi-example-api.yaml';
 import otherApiEntity from './other-example-api.yaml';
 
@@ -41,6 +42,7 @@ createDevApp()
             items: [
               openapiApiEntity,
               asyncapiApiEntity,
+              jsonschemaApiEntity,
               graphqlApiEntity,
               otherApiEntity,
             ],
@@ -87,6 +89,19 @@ createDevApp()
       </Page>
     ),
   })
+  .addPage({
+    title: 'JSON Schema',
+    element: (
+      <Page themeId="home">
+        <Header title="JSON Schema" />
+        <Content>
+          <EntityProvider entity={(jsonschemaApiEntity as any) as Entity}>
+            <EntityApiDefinitionCard />
+          </EntityProvider>
+        </Content>
+      </Page>
+    ),
+  })
   .addPage({
     title: 'GraphQL',
     element: (

plugins/api-docs/dev/jsonschema-example-api.yaml

@@ -0,0 +1,32 @@
+apiVersion: backstage.io/v1alpha1
+kind: API
+metadata:
+  name: persons
+  description: Person dataset
+spec:
+  type: jsonschema
+  lifecycle: experimental
+  owner: team-c
+  # From https://json-schema.org/learn/miscellaneous-examples.html
+  definition: |
+    {
+      "$id": "https://example.com/person.schema.json",
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "title": "Person",
+      "type": "object",
+      "properties": {
+        "firstName": {
+          "type": "string",
+          "description": "The person's first name."
+        },
+        "lastName": {
+          "type": "string",
+          "description": "The person's last name."
+        },
+        "age": {
+          "description": "Age in years which must be equal to or greater than zero.",
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    }

plugins/api-docs/package.json

@@ -38,6 +38,9 @@
     "@material-ui/core": "^4.11.0",
     "@material-ui/icons": "^4.9.1",
     "@material-ui/lab": "4.0.0-alpha.45",
+    "@stoplight/json-schema-viewer": "^4.0.0-beta.16",
+    "@stoplight/mosaic": "^1.0.0-beta.46",
+    "@stoplight/reporter": "^1.10.0",
     "@types/react": "^16.9",
     "graphiql": "^1.0.0-alpha.10",
     "graphql": "^15.3.0",

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

@@ -16,6 +16,7 @@
 import React from 'react';
 import { AsyncApiDefinitionWidget } from '../AsyncApiDefinitionWidget';
 import { GraphQlDefinitionWidget } from '../GraphQlDefinitionWidget';
+import { JsonSchemaDefinitionWidget } from '../JsonSchemaDefinitionWidget';
 import { OpenApiDefinitionWidget } from '../OpenApiDefinitionWidget';
 
 export type ApiDefinitionWidget = {
@@ -51,5 +52,13 @@ export function defaultDefinitionWidgets(): ApiDefinitionWidget[] {
         <GraphQlDefinitionWidget definition={definition} />
       ),
     },
+    {
+      type: 'jsonschema',
+      title: 'JSON Schema',
+      rawLanguage: 'json',
+      component: definition => (
+        <JsonSchemaDefinitionWidget definition={definition} />
+      ),
+    },
   ];
 }

plugins/api-docs/src/components/JsonSchemaDefinitionWidget/JsonSchemaDefinitionWidget.test.tsx

@@ -0,0 +1,61 @@
+/*
+ * 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 { renderInTestApp } from '@backstage/test-utils';
+import React from 'react';
+import { JsonSchemaDefinitionWidget } from './JsonSchemaDefinitionWidget';
+
+describe('<JsonSchemaDefinitionWidget />', () => {
+  it('renders json schema', async () => {
+    // From https://json-schema.org/learn/miscellaneous-examples.html
+    const definition = `
+{
+  "$id": "https://example.com/person.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Person",
+  "type": "object",
+  "properties": {
+    "firstName": {
+      "type": "string",
+      "description": "The person's first name."
+    },
+    "lastName": {
+      "type": "string",
+      "description": "The person's last name."
+    },
+    "age": {
+      "description": "Age in years which must be equal to or greater than zero.",
+      "type": "integer",
+      "minimum": 0
+    }
+  }
+}
+    `;
+    const { getByText } = await renderInTestApp(
+      <JsonSchemaDefinitionWidget definition={definition} />,
+    );
+
+    expect(getByText(/lastName/i)).toBeInTheDocument();
+    expect(getByText(/The person's last name./i)).toBeInTheDocument();
+  });
+
+  it('renders error if definition is missing', async () => {
+    const { getByText } = await renderInTestApp(
+      <JsonSchemaDefinitionWidget definition="{}" />,
+    );
+    expect(getByText(/No schema defined/i)).toBeInTheDocument();
+  });
+});

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

@@ -0,0 +1,50 @@
+/*
+ * 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 { useTheme } from '@material-ui/core';
+import { JsonSchemaViewer } from '@stoplight/json-schema-viewer';
+import { injectStyles, useThemeStore } from '@stoplight/mosaic';
+import React, { useMemo } from 'react';
+import { useEffectOnce } from 'react-use';
+
+injectStyles();
+
+type Props = {
+  definition: any;
+};
+
+export const JsonSchemaDefinitionWidget = ({ definition }: Props) => {
+  const schema = useMemo(() => JSON.parse(definition), [definition]);
+  const theme = useTheme();
+  const themeStore = useThemeStore();
+
+  useEffectOnce(() => {
+    themeStore.setColor('background', theme.palette.background.paper);
+    themeStore.setColor('text', theme.palette.text.primary);
+    themeStore.setColor('primary', theme.palette.primary.main);
+    themeStore.setColor('success', theme.palette.success.main);
+    themeStore.setColor('warning', theme.palette.warning.main);
+    themeStore.setColor('danger', theme.palette.error.main);
+    themeStore.setMode(theme.palette.type);
+  });
+  return (
+    <JsonSchemaViewer
+      schema={schema}
+      emptyText="No schema defined"
+      defaultExpandedDepth={5}
+    />
+  );
+};

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

plugins/api-docs/src/components/index.ts

@@ -20,3 +20,4 @@ export * from './AsyncApiDefinitionWidget';
 export * from './ComponentsCards';
 export * from './OpenApiDefinitionWidget';
 export * from './PlainApiDefinitionWidget';
+export * from './JsonSchemaDefinitionWidget';