Swagger UI

package.json

@@ -142,6 +142,7 @@
     "react-router-dom": "5.3.4",
     "sanitize-html": "2.7.3",
     "schema-dts": "1.1.0",
+    "swagger-ui-react": "5.17.14",
     "timing-functions": "2.0.1",
     "tippy.js": "6.3.7",
     "type-fest": "3.1.0",
@@ -179,6 +180,7 @@
     "@types/react-dom": "18.2.0",
     "@types/react-router-dom": "5.3.3",
     "@types/sanitize-html": "2.6.2",
+    "@types/swagger-ui-react": "^4.18.3",
     "@types/url-join": "4.0.1",
     "@types/uuid": "8.3.4",
     "@typescript-eslint/eslint-plugin": "5.42.0",
@@ -216,6 +218,7 @@
     "mini-css-extract-plugin": "2.6.1",
     "node-sass-json-importer": "4.3.0",
     "npm-run-all": "4.1.5",
+    "openapi-types": "12.1.3",
     "prettier": "2.7.1",
     "process": "0.11.10",
     "react-test-renderer": "18.2.0",

src/app/components/App.tsx

@@ -271,6 +271,12 @@ const HelpResults = lazy(
       /* webpackChunkName: "help-results" */ '../../help/components/results/Results'
     )
 );
+const ApiDocumentationPage = lazy(
+  () =>
+    import(
+      /* webpackChunkName: "documentation" */ '../../help/components/entry/ApiDocumentation'
+    )
+);
 
 // Contact
 const ContactForm = lazy(
@@ -546,6 +552,10 @@ const App = () => {
               path={LocationToPath[Location.ReleaseNotesResults]}
               component={HelpResults}
             />
+            <Route
+              path={LocationToPath[Location.Documentation]}
+              component={ApiDocumentationPage}
+            />
             {/* Contact */}
             <Route
               path={LocationToPath[Location.ContactGeneric]}

src/app/config/urls.ts

@@ -75,6 +75,7 @@ export enum Location {
   // Help
   HelpEntry = 'HelpEntry',
   HelpResults = 'HelpResults',
+  Documentation = 'Documentation',
   // Release Notes
   ReleaseNotesEntry = 'ReleaseNotesEntry',
   ReleaseNotesResults = 'ReleaseNotesResults',
@@ -131,6 +132,7 @@ export const LocationToPath: Record<Location, string> = {
   // Help
   [Location.HelpEntry]: '/help/:accession',
   [Location.HelpResults]: '/help',
+  [Location.Documentation]: '/documentation/:definition?',
   // News
   [Location.ReleaseNotesEntry]: '/release-notes/:accession+',
   [Location.ReleaseNotesResults]: '/release-notes',

src/help/components/entry/ApiDocumentation.tsx

@@ -0,0 +1,57 @@
+import { Tabs, Tab } from 'franklin-sites';
+import { useEffect } from 'react';
+import {
+  generatePath,
+  Link,
+  useHistory,
+  useRouteMatch,
+} from 'react-router-dom';
+
+import DocumentationTab from './ApiDocumentationTab';
+
+import { LocationToPath, Location } from '../../../app/config/urls';
+import { apiDocsDefinitionToString } from '../../config/apiDocumentation';
+
+import { ApiDocsDefinition } from '../../types/apiDocumentation';
+
+import 'swagger-ui-react/swagger-ui.css';
+
+const ApiDocumentation = () => {
+  const history = useHistory();
+  const match = useRouteMatch<{ definition: ApiDocsDefinition }>(
+    LocationToPath[Location.Documentation]
+  );
+  const definition = match?.params.definition;
+  useEffect(() => {
+    if (!definition) {
+      history.replace({
+        pathname: generatePath(LocationToPath[Location.Documentation], {
+          definition: ApiDocsDefinition.uniprotkb,
+        }),
+      });
+    }
+  }, [definition, history]);
+  return (
+    <Tabs active={definition}>
+      {Array.from(apiDocsDefinitionToString).map(([id, label]) => (
+        <Tab
+          title={
+            <Link
+              to={generatePath(LocationToPath[Location.Documentation], {
+                definition: id,
+              })}
+            >
+              {label}
+            </Link>
+          }
+          id={id}
+          key={id}
+        >
+          <DocumentationTab />
+        </Tab>
+      ))}
+    </Tabs>
+  );
+};
+
+export default ApiDocumentation;

src/help/components/entry/ApiDocumentationTab.tsx

@@ -0,0 +1,171 @@
+import { ReactNode, useCallback, useEffect, useMemo } from 'react';
+import { useHistory, useRouteMatch } from 'react-router-dom';
+import { Location as HistoryLocation } from 'history';
+import { Card, Loader } from 'franklin-sites';
+import SwaggerUI from 'swagger-ui-react';
+import { frame } from 'timing-functions';
+import type { OpenAPIV3 } from 'openapi-types';
+
+import HTMLHead from '../../../shared/components/HTMLHead';
+import ErrorBoundary from '../../../shared/components/error-component/ErrorBoundary';
+import ErrorHandler from '../../../shared/components/error-pages/ErrorHandler';
+import { SidebarLayout } from '../../../shared/components/layouts/SideBarLayout';
+import InPageNav from '../../../shared/components/InPageNav';
+
+import useDataApi from '../../../shared/hooks/useDataApi';
+
+import {
+  getIdToOperation,
+  getLayoutAction,
+  getTagIdsAndSections,
+  tagNameToId,
+} from '../../utils/apiDocumentation';
+
+import { LocationToPath, Location } from '../../../app/config/urls';
+import apiUrls from '../../config/apiUrls';
+
+import { ApiDocsDefinition } from '../../types/apiDocumentation';
+
+import 'swagger-ui-react/swagger-ui.css';
+import styles from './styles/api-documentation.module.scss';
+
+const OperationTag = ({
+  tagObj,
+  children,
+}: {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  tagObj: any;
+  children: ReactNode;
+}) => {
+  const tagDetails = tagObj.get('tagDetails');
+  return (
+    <div className={styles['operation-tag']}>
+      <h1 id={tagNameToId(tagDetails.get('name'))} className="medium">
+        {tagDetails.get('name')}
+      </h1>
+      {/* eslint-disable-next-line react/no-danger */}
+      <p dangerouslySetInnerHTML={{ __html: tagDetails.get('description') }} />
+      <hr />
+      {children}
+    </div>
+  );
+};
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const AugmentingLayout = ({ getComponent, dispatch, spec: getSpec }: any) => {
+  const history = useHistory();
+  const BaseLayout = getComponent('BaseLayout', true);
+  const [tagIds, sections, idToOperation] = useMemo(() => {
+    const spec = getSpec().get('json');
+    const idToOperation = getIdToOperation(spec.get('paths').toJSON());
+    return [
+      ...getTagIdsAndSections(spec, idToOperation, styles['section-path']),
+      idToOperation,
+    ];
+  }, [getSpec]);
+  const openOperationAtLocation = useCallback(
+    (location: HistoryLocation) => {
+      const id = location.hash.replace('#', '');
+      if (tagIds.has(id)) {
+        for (const operation of idToOperation.values()) {
+          dispatch(getLayoutAction(operation, false));
+        }
+      } else {
+        const operation = idToOperation.get(id);
+        if (operation?.tag && operation?.operationId) {
+          dispatch(getLayoutAction(operation, true));
+        }
+      }
+    },
+    [dispatch, idToOperation, tagIds]
+  );
+
+  useEffect(() => {
+    const unlisten = history.listen((location) =>
+      frame().then(() => openOperationAtLocation(location))
+    );
+    openOperationAtLocation(history.location);
+    return unlisten;
+  }, [history, openOperationAtLocation]);
+
+  return (
+    <SidebarLayout
+      className={styles.wider}
+      sidebar={
+        <div className={styles.sidebar}>
+          <InPageNav sections={sections} />
+        </div>
+      }
+    >
+      <HTMLHead title="UniProt website API documentation">
+        <meta name="robots" content="noindex" />
+      </HTMLHead>
+      <Card className={styles.content}>
+        <ErrorBoundary>
+          <BaseLayout />
+        </ErrorBoundary>
+      </Card>
+    </SidebarLayout>
+  );
+};
+
+const AugmentingLayoutPlugin = () => ({
+  components: {
+    AugmentingLayout,
+    Schemes: () => null,
+    InfoContainer: () => null,
+    ServersContainer: () => null,
+    OperationTag,
+  },
+});
+
+const ApiDocumentationTab = () => {
+  const match = useRouteMatch<{ definition: ApiDocsDefinition }>(
+    LocationToPath[Location.Documentation]
+  );
+  const definition = match?.params.definition;
+
+  const data = useDataApi<OpenAPIV3.Document>(
+    definition && apiUrls.apiDocumnentationDefinition(definition)
+  );
+
+  if (data.loading) {
+    return <Loader progress={data.progress} />;
+  }
+
+  if (data.error || !data.data) {
+    return <ErrorHandler status={data.status} error={data.error} fullPage />;
+  }
+
+  // TODO: enable request snippets eg python. https://www.ebi.ac.uk/panda/jira/browse/TRM-31649
+  // Leaving this config here in case it is useful in the future:
+  // requestSnippets: {
+  // generators: {
+  //   curl_bash: {
+  //     title: 'cURL (bash)',
+  //     syntax: 'bash',
+  //   },
+  //   curl_powershell: {
+  //     title: 'cURL (PowerShell)',
+  //     syntax: 'powershell',
+  //   },
+  //   curl_cmd: {
+  //     title: 'cURL (CMD)',
+  //     syntax: 'bash',
+  //   },
+  //   python_requests: {
+  //     title: 'Python (requests)',
+  //     syntax: 'python',
+  //   },
+  // },
+
+  return !definition ? null : (
+    <SwaggerUI
+      spec={data.data}
+      plugins={[AugmentingLayoutPlugin]}
+      layout="AugmentingLayout"
+    />
+  );
+};
+
+export default ApiDocumentationTab;

src/help/components/entry/styles/api-documentation.module.scss

@@ -0,0 +1,76 @@
+@import 'franklin-sites/src/styles/colours';
+@import 'franklin-sites/src/styles/settings';
+@import 'franklin-sites/src/styles/mixins';
+
+.wider {
+  grid-template-columns: 3rem calc(1.3 * var(--sidebar-size) - 3rem) minmax(
+      min-content,
+      1fr
+    );
+}
+
+.sidebar {
+  .section-path {
+    margin-left: 0.75rem;
+  }
+}
+
+.content {
+  .operation-tag {
+    &:not(:first-child) {
+      margin-top: 3rem;
+    }
+    h1 {
+      margin: 1rem 0;
+    }
+    p {
+      margin-bottom: 0.5rem;
+    }
+
+    hr {
+      border: none;
+      height: 0.125rem;
+      background-color: $colour-platinum;
+      margin-bottom: 0.5rem;
+    }
+  }
+
+  :global(.swagger-ui) {
+    :global(.scheme-container) {
+      display: none;
+    }
+
+    :global(.opblock) {
+      border-radius: 0px;
+    }
+
+    :global(.opblock.opblock-get),
+    :global(.opblock.opblock-post) {
+      border: 0px;
+      :global(.arrow) {
+        fill: white;
+      }
+
+      :global(.opblock-summary) {
+        border: 0px;
+        background-color: $colour-sea-blue;
+      }
+      :global(.opblock-summary-method) {
+        border-radius: 0px;
+      }
+
+      :global(.opblock-summary-path),
+      :global(.opblock-summary-description) {
+        color: white;
+      }
+    }
+
+    :global(.opblock.opblock-get) :global(.opblock-summary-method) {
+      background: lighten($colour-sea-blue, 10%);
+    }
+
+    // :global(.opblock.opblock-post) :global(.opblock-summary-method) {
+    //   background: mediumseagreen;
+    // }
+  }
+}

src/help/config/apiDocumentation.ts

@@ -0,0 +1,12 @@
+import { ApiDocsDefinition } from '../types/apiDocumentation';
+
+export const apiDocsDefinitionToString = new Map([
+  [ApiDocsDefinition.uniprotkb, 'UniProtKB'],
+  [ApiDocsDefinition.uniref, 'UniRef'],
+  [ApiDocsDefinition.uniparc, 'UniParc'],
+  [ApiDocsDefinition.proteomes, 'Proteomes'],
+  [ApiDocsDefinition.support_data, 'Supporting Data'],
+  [ApiDocsDefinition.aa, 'Automatic Annotation'],
+  [ApiDocsDefinition.idmapping, 'ID Mapping'],
+  [ApiDocsDefinition.async_download, 'Async Download'],
+]);