[JUG-14] - Use @stoplight/elements to show the OpenAPI specification

.changeset/rare-avocados-work.md

@@ -0,0 +1,5 @@
+---
+'@pagopa-dev/juggler': minor
+---
+
+Replace swagger-ui-react with @stoplight/elements

package.json

@@ -9,7 +9,7 @@
     },
     "openapi": {
       "pn": {
-        "deliveryURL": "https://github.com/pagopa/pn-delivery/raw/d499410/docs/openapi/api-external-b2b-pa-v1.yaml",
+        "deliveryURL": "https://raw.githubusercontent.com/pagopa/pn-delivery/5534854/docs/openapi/api-external-b2b-pa.yaml",
         "streamURL": "https://github.com/pagopa/pn-delivery-push/raw/a886f32/docs/openapi/api-external-b2b-webhook-v1.yaml"
       },
       "io": {
@@ -35,7 +35,7 @@
     "dev": "npm run generate:api && npm run compile && node -r dotenv/config dist/main.js dotenv_config_path=.env.default",
     "build": "npm run compile && next build",
     "lint": "next lint",
-    "format": "prettier --write \"./**/*.ts\"",
+    "format": "prettier --write \"./**/*.{ts,tsx}\"",
     "dev:pn": "OPENAPI_URL=$npm_package_config_openapi_pn_deliveryURL npm run dev",
     "dev:io": "OPENAPI_URL=$npm_package_config_openapi_io_apiPublicURL npm run dev",
     "dev:iosign": "OPENAPI_URL=$npm_package_config_openapi_iosign_issuerURL npm run dev",
@@ -54,7 +54,6 @@
     "@types/jest": "^29.4.0",
     "@types/node": "^18.15.11",
     "@types/react": "18.0.28",
-    "@types/swagger-ui-react": "^4.11.0",
     "concurrently": "^7.6.0",
     "dependency-check": "^4.1.0",
     "dotenv": "^16.0.3",
@@ -74,6 +73,7 @@
     "@emotion/styled": "^11.10.6",
     "@mui/material": "^5.11.11",
     "@pagopa/ts-commons": "^10.14.2",
+    "@stoplight/elements": "^7.7.18",
     "@stoplight/prism-cli": "^4.10.5",
     "@stoplight/prism-http": "^4.10.5",
     "@textea/json-viewer": "^1.24.5",
@@ -85,7 +85,6 @@
     "newtype-ts": "^0.3.5",
     "next": "^13.1.6",
     "pino": "^8.8.0",
-    "swagger-ui-react": "^4.18.0",
     "swr": "^2.0.4"
   }
 }

src/adapters/express/AppEnv.ts

@@ -4,6 +4,7 @@ import { Config } from '../../config';
 import { Capabilities } from '../../domain/Capabilities';
 import { makeRequestResponseStore } from '../array/makeRequestResponseStore';
 import { makeMock } from '../prism/makeMock';
+import { makeOpenAPIParser } from '../swagger-parser/makeOpenAPIParser';
 
 export type AppEnv = Capabilities & Config;
 
@@ -15,10 +16,12 @@ export const makeAppEnv = (config: Config): TE.TaskEither<Error, AppEnv> =>
     TE.Do,
     TE.apS('mock', makeMock(config.openapi.URL)),
     TE.apS('requestResponseStore', TE.of(makeRequestResponseStore([]))),
-    TE.map(({ mock, requestResponseStore }) => ({
+    TE.apS('openAPIParser', TE.of(makeOpenAPIParser())),
+    TE.map(({ mock, requestResponseStore, openAPIParser }) => ({
       ...config,
       mock,
       requestResponseReader: requestResponseStore,
       requestResponseWriter: requestResponseStore,
+      openApiParser: openAPIParser,
     }))
   );

src/adapters/express/getOpenApiRouter.ts

@@ -1,8 +1,7 @@
 import express from 'express';
 import { pipe } from 'fp-ts/lib/function';
-import * as E from 'fp-ts/Either';
-import * as TE from 'fp-ts/TaskEither';
-import SwaggerParser from '@apidevtools/swagger-parser';
+import * as RTE from 'fp-ts/ReaderTaskEither';
+import { getOpenApiSpec } from '../../useCases/getOpenApiSpec';
 import { AppEnv } from './AppEnv';
 import { problemDetail500 } from './errors';
 
@@ -12,13 +11,13 @@ export const makeGetOpenApiRouter = (env: AppEnv): express.Router => {
   // In the future this feature can be mapped into the domain
   router.get('/api/openapi', (_req, res) =>
     pipe(
-      TE.tryCatch(() => SwaggerParser.validate(env.openapi.URL), E.toError),
-      TE.bimap(
-        () => res.status(500).json(problemDetail500),
-        (openapi) => res.status(200).json(openapi)
+      getOpenApiSpec(env.server)(env.openapi.URL),
+      RTE.fold(
+        (_) => RTE.of(res.status(500).json(problemDetail500)),
+        (spec) => RTE.of(res.status(200).json(spec))
       ),
-      TE.toUnion
-    )()
+      RTE.toUnion
+    )(env)()
   );
 
   return router;

src/adapters/swagger-parser/makeOpenAPIParser.ts

@@ -0,0 +1,18 @@
+import * as TE from 'fp-ts/TaskEither';
+import { pipe } from 'fp-ts/function';
+import SwaggerParser from '@apidevtools/swagger-parser';
+import * as E from 'fp-ts/Either';
+import { OpenAPIParser } from '../../domain/OpenAPISpec';
+
+export const makeOpenAPIParser = (): OpenAPIParser => ({
+  parse: (url) =>
+    pipe(
+      TE.tryCatch(() => SwaggerParser.validate(url), E.toError),
+      TE.map(
+        (openapi) =>
+          // TODO: we should change the baseURL coming from the OpenAPI spec. We want them to have the Juggler's baseUrl.
+          // FIXME: Continue here
+          openapi
+      )
+    ),
+});

src/domain/Capabilities.ts

@@ -7,6 +7,7 @@ import {
   RequestResponseReader,
   RequestResponseWriter,
 } from './RequestResponse';
+import { OpenAPIParser } from './OpenAPISpec';
 
 /**
  * Maps the capabilities to a given property name. Pick the capability using the
@@ -18,4 +19,5 @@ export type Capabilities = {
   mock: Mock;
   requestResponseReader: RequestResponseReader;
   requestResponseWriter: RequestResponseWriter;
+  openApiParser: OpenAPIParser;
 };

src/domain/OpenAPISpec.ts

@@ -0,0 +1,15 @@
+import * as TE from 'fp-ts/TaskEither';
+import { OpenAPI } from 'openapi-types';
+
+// For now use the types of OpenAPI types
+export type OpenAPISpec = OpenAPI.Document;
+
+/**
+ * This type express the capability to parse an OpenAPI specification from an URL.
+ */
+export type OpenAPIParser = {
+  /**
+   * Given an URL, parse the OpenAPI specification.
+   */
+  parse: (url: string) => TE.TaskEither<Error, OpenAPISpec>;
+};

src/domain/__tests__/data.ts

@@ -34,6 +34,7 @@ export const makeFakeCapabilities = (defaultData: typeof data = data) => {
     mock: mock<Capabilities['mock']>(),
     requestResponseReader: mock<Capabilities['requestResponseReader']>(),
     requestResponseWriter: mock<Capabilities['requestResponseWriter']>(),
+    openApiParser: mock<Capabilities['openApiParser']>(),
   };
   // default behavior
   mocked.mock.generateResponse.mockReturnValue(

src/pages/openapi.tsx

@@ -1,6 +1,15 @@
-import SwaggerUI from 'swagger-ui-react';
-import 'swagger-ui-react/swagger-ui.css';
+import { API } from '@stoplight/elements';
+import '@stoplight/elements/styles.min.css';
 
-const ApiViewer = () => <SwaggerUI url="/api/openapi" />;
+const ApiViewer = () => (
+  <API
+    apiDescriptionUrl="/api/openapi"
+    basePath={'/ui/openapi'}
+    router={typeof window === 'undefined' ? 'memory' : 'history'}
+    hideInternal={true}
+    hideExport={true}
+    hideTryIt={true} // We are going to enable in later
+  />
+);
 
 export default ApiViewer;

src/useCases/getOpenApiSpec.ts

@@ -0,0 +1,11 @@
+import { pipe } from 'fp-ts/function';
+import * as R from 'fp-ts/Reader';
+import { Config } from '../config';
+import { Capabilities } from '../domain/Capabilities';
+
+export const getOpenApiSpec =
+  (_serverConfig: Config['server']) => (openApiURL: string) =>
+    pipe(
+      R.ask<Pick<Capabilities, 'openApiParser'>>(),
+      R.map(({ openApiParser }) => openApiParser.parse(openApiURL))
+    );