Fix issue backstage#8090 adds support for OpenAPI 3.1 by replacing Sw…

…aggerUI with openapi-explorer

Signed-off-by: Brian McManus <bmcmanus@gmail.com>

.changeset/wise-timers-decide.md

@@ -0,0 +1,6 @@
+---
+'@backstage/catalog-model': minor
+'@backstage/plugin-api-docs': minor
+---
+
+Replaced swagger-ui with openapi-explorer so that OpenAPI 3.1 Specifications can be viewed by api-docs

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

@@ -13,3 +13,4 @@ spec:
     - ./apis/swapi-graphql.yaml
     - ./apis/wayback-archive-api.yaml
     - ./apis/wayback-search-api.yaml
+    - ./apis/petstore-31-api.yaml

packages/catalog-model/examples/apis/petstore-31-api.yaml

@@ -0,0 +1,143 @@
+apiVersion: backstage.io/v1alpha1
+kind: API
+metadata:
+  name: petstore31
+  description: The petstore31 API
+  tags:
+    - store
+    - rest
+  links:
+    - url: https://github.com/swagger-api/swagger-petstore
+      title: GitHub Repo
+      icon: github
+    - url: https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v3.0/petstore.yaml
+      title: API Spec
+      icon: code
+spec:
+  type: openapi
+  lifecycle: experimental
+  owner: team-c
+  definition: |
+    openapi: "3.1.0"
+    info:
+      version: 1.0.0
+      title: Swagger 3.1 Petstore
+      license:
+        name: MIT
+    servers:
+      - url: http://petstore.swagger.io/v1
+    webhooks:
+      newPet:
+        post:
+          requestBody:
+            description: Information about a new pet in the system
+            content:
+              application/json:
+                schema:
+                  $ref: "#/components/schemas/Pet"
+          responses:
+            "200":
+              description: Return a 200 status to indicate that the data was received successfully
+    paths:
+      /pets:
+        get:
+          summary: List all pets
+          operationId: listPets
+          tags:
+            - pets
+          parameters:
+            - name: limit
+              in: query
+              description: How many items to return at one time (max 100)
+              required: false
+              schema:
+                type: integer
+                format: int32
+          responses:
+            '200':
+              description: A paged array of pets
+              headers:
+                x-next:
+                  description: A link to the next page of responses
+                  schema:
+                    type: string
+              content:
+                application/json:
+                  schema:
+                    $ref: "#/components/schemas/Pets"
+            default:
+              description: unexpected error
+              content:
+                application/json:
+                  schema:
+                    $ref: "#/components/schemas/Error"
+        post:
+          summary: Create a pet
+          operationId: createPets
+          tags:
+            - pets
+          responses:
+            '201':
+              description: Null response
+            default:
+              description: unexpected error
+              content:
+                application/json:
+                  schema:
+                    $ref: "#/components/schemas/Error"
+      /pets/{petId}:
+        get:
+          summary: Info for a specific pet
+          operationId: showPetById
+          tags:
+            - pets
+          parameters:
+            - name: petId
+              in: path
+              required: true
+              description: The id of the pet to retrieve
+              schema:
+                type: string
+          responses:
+            '200':
+              description: Expected response to a valid request
+              content:
+                application/json:
+                  schema:
+                    $ref: "#/components/schemas/Pet"
+            default:
+              description: unexpected error
+              content:
+                application/json:
+                  schema:
+                    $ref: "#/components/schemas/Error"
+    components:
+      schemas:
+        Pet:
+          type: object
+          required:
+            - id
+            - name
+          properties:
+            id:
+              type: integer
+              format: int64
+            name:
+              type: string
+            tag:
+              type: string
+        Pets:
+          type: array
+          items:
+            $ref: "#/components/schemas/Pet"
+        Error:
+          type: object
+          required:
+            - code
+            - message
+          properties:
+            code:
+              type: integer
+              format: int32
+            message:
+              type: string

plugins/api-docs/package.json

@@ -46,6 +46,7 @@
     "graphql": "^16.0.0",
     "graphql-ws": "^5.4.1",
     "isomorphic-form-data": "^2.0.0",
+    "openapi-explorer": "^0.11.483",
     "react-use": "^17.2.4",
     "swagger-ui-react": "^4.11.1"
   },

plugins/api-docs/src/components/OpenApiDefinitionWidget/OpenApiDefinition.tsx

@@ -14,142 +14,43 @@
  * limitations under the License.
  */
 
-import { makeStyles } from '@material-ui/core/styles';
-import React, { useEffect, useState } from 'react';
-import SwaggerUI from 'swagger-ui-react';
-import 'swagger-ui-react/swagger-ui.css';
-
-const useStyles = makeStyles(theme => ({
-  root: {
-    '& .swagger-ui': {
-      fontFamily: theme.typography.fontFamily,
-      color: theme.palette.text.primary,
-
-      [`& .scheme-container`]: {
-        backgroundColor: theme.palette.background.default,
-      },
-      [`& .opblock-tag,
-          .opblock-tag small,
-          table thead tr td,
-          table thead tr th`]: {
-        fontFamily: theme.typography.fontFamily,
-        color: theme.palette.text.primary,
-        borderColor: theme.palette.divider,
-      },
-      [`& section.models,
-          section.models.is-open h4`]: {
-        borderColor: theme.palette.divider,
-      },
-      [`& .model-title,
-          .model .renderedMarkdown,
-          .model .description`]: {
-        fontFamily: theme.typography.fontFamily,
-        fontWeight: theme.typography.fontWeightRegular,
-      },
-      [`& h1, h2, h3, h4, h5, h6,
-          .errors h4, .error h4, .opblock h4, section.models h4,
-          .response-control-media-type__accept-message,
-          .opblock-summary-description,
-          .opblock-summary-operation-id,
-          .opblock-summary-path,
-          .opblock-summary-path__deprecated,
-          .opblock-description-wrapper,
-          .opblock-external-docs-wrapper,
-          .opblock-section-header .btn,
-          .opblock-section-header>label,
-          .scheme-container .schemes>label,a.nostyle,
-          .parameter__name,
-          .response-col_status,
-          .response-col_links,
-          .error .btn,
-          .info .title,
-          .info .base-url`]: {
-        fontFamily: theme.typography.fontFamily,
-        color: theme.palette.text.primary,
-      },
-      [`& .opblock .opblock-section-header,
-          .model-box,
-          section.models .model-container`]: {
-        background: theme.palette.background.default,
-      },
-      [`& .prop-format,
-          .parameter__in`]: {
-        color: theme.palette.text.disabled,
-      },
-      [`& table.model,
-          .parameter__type,
-          .model.model-title,
-          .model-title,
-          .model span,
-          .model .brace-open,
-          .model .brace-close,
-          .model .property.primitive,
-          .model .renderedMarkdown,
-          .model .description,
-          .errors small`]: {
-        color: theme.palette.text.secondary,
-      },
-      [`& .parameter__name.required:after`]: {
-        color: theme.palette.warning.dark,
-      },
-      [`& table.model,
-          table.model .model,
-          .opblock-external-docs-wrapper`]: {
-        fontSize: theme.typography.fontSize,
-      },
-      [`& table.headers td`]: {
-        color: theme.palette.text.primary,
-        fontWeight: theme.typography.fontWeightRegular,
-      },
-      [`& .model-hint`]: {
-        color: theme.palette.text.hint,
-        backgroundColor: theme.palette.background.paper,
-      },
-      [`& .opblock-summary-method,
-          .info a`]: {
-        fontFamily: theme.typography.fontFamily,
-      },
-      [`& .info, .opblock, .tab`]: {
-        [`& li, p`]: {
-          fontFamily: theme.typography.fontFamily,
-          color: theme.palette.text.primary,
-        },
-      },
-      [`& a`]: {
-        color: theme.palette.primary.main,
-      },
-      [`& .renderedMarkdown code`]: {
-        color: theme.palette.secondary.light,
-      },
-      [`& .property-row td:first-child`]: {
-        color: theme.palette.text.primary,
-      },
-      [`& span.prop-type`]: {
-        color: theme.palette.success.light,
-      },
-    },
-  },
-}));
+import React from 'react';
+import { useTheme } from '@material-ui/core';
+import { makeStyles } from '@material-ui/core';
+import 'openapi-explorer';
+import { BackstageTheme } from '@backstage/theme';
 
 export type OpenApiDefinitionProps = {
   definition: string;
 };
 
 export const OpenApiDefinition = ({ definition }: OpenApiDefinitionProps) => {
-  const classes = useStyles();
-
-  // Due to a bug in the swagger-ui-react component, the component needs
-  // to be created without content first.
-  const [def, setDef] = useState('');
-
-  useEffect(() => {
-    const timer = setTimeout(() => setDef(definition), 0);
-    return () => clearTimeout(timer);
-  }, [definition, setDef]);
-
+  const theme: BackstageTheme = useTheme();
   return (
-    <div className={classes.root}>
-      <SwaggerUI spec={def} url="" deepLinking />
+    <div>
+      <openapi-explorer
+        primary-color={
+          theme.palette.info
+        } /* Buttons and background of code blocks */
+        secondary-color={theme.palette.primary.main} /* 1px lines */
+        bg-color={theme.palette.background.default}
+        bg-header-color={theme.palette.background.paper}
+        text-color={theme.palette.text.primary}
+        header-color={theme.palette.text.primary}
+        nav-bg-color={theme.palette.background.paper}
+        nav-text-color={theme.palette.text.primary}
+        nav-hover-bg-color={theme.palette.background.default}
+        nav-hover-text-color={theme.palette.text.primary}
+        nav-item-spacing={theme.spacing(1)}
+        show-info
+        allow-authentication
+        allow-try
+        include-nulls
+        allow-search
+        allow-advaned-search
+        allow-server-selection
+        spec-url={definition}
+      />
     </div>
   );
 };