Merge pull request #616 from blockscout/swagger-new

Swagger new

.env.template

@@ -48,6 +48,7 @@ NEXT_PUBLIC_API_PROTOCOL=__PLACEHOLDER_FOR_NEXT_PUBLIC_API_PROTOCOL__
 NEXT_PUBLIC_API_PORT=__PLACEHOLDER_FOR_NEXT_PUBLIC_API_PORT__
 NEXT_PUBLIC_STATS_API_HOST=__PLACEHOLDER_FOR_NEXT_PUBLIC_STATS_API_HOST__
 NEXT_PUBLIC_VISUALIZE_API_HOST=__PLACEHOLDER_FOR_NEXT_PUBLIC_VISUALIZE_API_HOST__
+NEXT_PUBLIC_API_SPEC_URL=__PLACEHOLDER_FOR_NEXT_PUBLIC_API_SPEC_URL__
 
 # external services config
 NEXT_PUBLIC_SENTRY_DSN=__PLACEHOLDER_FOR_NEXT_PUBLIC_SENTRY_DSN__

README.md

@@ -79,6 +79,7 @@ The app instance could be customized by passing following variables to NodeJS en
 | NEXT_PUBLIC_HOMEPAGE_SHOW_AVG_BLOCK_TIME | `boolean` *(optional)* | Set to false if average block time is useless for the network | `true` |
 | NEXT_PUBLIC_DOMAIN_WITH_AD | `string` *(optional)* | The domain on which we display ads | `blockscout.com` |
 | NEXT_PUBLIC_AD_ADBUTLER_ON | `boolean` *(optional)* | Set to true to show Adbutler banner instead of Coinzilla banner | `false` |
+| NEXT_PUBLIC_API_SPEC_URL | `string` *(optional)* | Spec to be displayed on api-docs page | `https://raw.githubusercontent.com/blockscout/blockscout-api-v2-swagger/main/swagger.yaml` |
 ### App configuration
 
 | Variable | Type | Description | Default value

configs/app/config.ts

@@ -126,6 +126,9 @@ const config = Object.freeze({
   walletConnect: {
     projectId: getEnvValue(process.env.NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID),
   },
+  apiDoc: {
+    specUrl: getEnvValue(process.env.NEXT_PUBLIC_API_SPEC_URL),
+  },
 });
 
 export default config;

configs/envs/.env.common

@@ -9,6 +9,8 @@ NEXT_PUBLIC_APP_ENV=development
 NEXT_PUBLIC_BLOCKSCOUT_VERSION=v4.1.7-beta
 NEXT_PUBLIC_FOOTER_GITHUB_LINK=https://github.com/blockscout/blockscout
 NEXT_PUBLIC_FOOTER_TWITTER_LINK=https://www.twitter.com/blockscoutcom
+NEXT_PUBLIC_API_SPEC_URL=https://raw.githubusercontent.com/blockscout/blockscout-api-v2-swagger/main/swagger.yaml
+
 
 # api config
 NEXT_PUBLIC_API_HOST=blockscout.com

configs/envs/.env.localhost

@@ -17,6 +17,7 @@ NEXT_PUBLIC_HOMEPAGE_CHARTS=['daily_txs','coin_price','market_cup']
 NEXT_PUBLIC_HOMEPAGE_PLATE_GRADIENT=radial-gradient(at 12% 37%, hsla(324,73%,67%,1) 0px, transparent 50%), radial-gradient(at 62% 14%, hsla(256,87%,73%,1) 0px, transparent 50%), radial-gradient(at 84% 80%, hsla(128,75%,73%,1) 0px, transparent 50%), radial-gradient(at 57% 46%, hsla(285,63%,72%,1) 0px, transparent 50%), radial-gradient(at 37% 30%, hsla(174,70%,61%,1) 0px, transparent 50%), radial-gradient(at 15% 86%, hsla(350,65%,70%,1) 0px, transparent 50%), radial-gradient(at 67% 57%, hsla(14,95%,76%,1) 0px, transparent 50%)
 #NEXT_PUBLIC_NETWORK_LOGO=https://placekitten.com/300/60
 #NEXT_PUBLIC_NETWORK_SMALL_LOGO=https://placekitten.com/300/300
+NEXT_PUBLIC_API_SPEC_URL=https://raw.githubusercontent.com/blockscout/blockscout-api-v2-swagger/main/swagger.yaml
 
 # network config
 NEXT_PUBLIC_NETWORK_NAME=POA

deploy/values/main/values.yaml

@@ -491,6 +491,7 @@ frontend:
         - "/token"
         - "/accounts"
         - "/visualize"
+        - "/api-docs"
 
   resources:
     limits:
@@ -571,3 +572,5 @@ frontend:
       _default: https://rpc.ankr.com/eth_goerli
     NEXT_PUBLIC_HOMEPAGE_CHARTS:
       _default: "['daily_txs','coin_price','market_cup']"
+    NEXT_PUBLIC_API_SPEC_URL: 
+      _default: https://raw.githubusercontent.com/blockscout/blockscout-api-v2-swagger/main/swagger.yaml

deploy/values/review/values.yaml

@@ -327,6 +327,7 @@ frontend:
         - "/tokens"
         - "/accounts"
         - "/visualize"
+        - "/api-docs"
 
   resources:
     limits:
@@ -408,3 +409,5 @@ frontend:
       _default: https://rpc.ankr.com/eth_goerli
     NEXT_PUBLIC_NETWORK_EXPLORERS:
       _default: "[{'title':'Anyblock','baseUrl':'https://explorer.anyblock.tools','paths':{'tx':'/ethereum/ethereum/goerli/transaction','address':'/ethereum/ethereum/goerli/address'}},{'title':'Etherscan','baseUrl':'https://goerli.etherscan.io/','paths':{'tx':'/tx','address':'/address'}}]"
+    NEXT_PUBLIC_API_SPEC_URL: 
+      _default: https://raw.githubusercontent.com/blockscout/blockscout-api-v2-swagger/main/swagger.yaml

lib/hooks/useNavItems.tsx

@@ -7,8 +7,8 @@ import abiIcon from 'icons/ABI.svg';
 import apiKeysIcon from 'icons/API.svg';
 import appsIcon from 'icons/apps.svg';
 import blocksIcon from 'icons/block.svg';
+import gearIcon from 'icons/gear.svg';
 import globeIcon from 'icons/globe-b.svg';
-// import gearIcon from 'icons/gear.svg';
 import privateTagIcon from 'icons/privattags.svg';
 import profileIcon from 'icons/profile.svg';
 import publicTagIcon from 'icons/publictags.svg';
@@ -44,6 +44,7 @@ export function isGroupItem(item: NavItem | NavGroupItem): item is NavGroupItem
 
 export default function useNavItems(): ReturnType {
   const isMarketplaceFilled = appConfig.marketplaceAppList.length > 0 && appConfig.network.rpcUrl;
+  const hasAPIDocs = appConfig.apiDoc.specUrl;
 
   const router = useRouter();
   const pathname = router.pathname;
@@ -57,6 +58,17 @@ export default function useNavItems(): ReturnType {
       // { text: 'Verified contracts', nextRoute: { pathname: '/verified_contracts' as const }, icon: verifiedIcon, isActive: pathname === '/verified_contracts', isNewUi: false },
     ];
 
+    const otherNavItems: Array<NavItem> = [
+      hasAPIDocs ? {
+        text: 'API documentation',
+        nextRoute: { pathname: '/api-docs' as const },
+        // FIXME: need icon for this item
+        icon: topAccountsIcon,
+        isActive: pathname === '/api-docs',
+        isNewUi: true,
+      } : null,
+    ].filter(notEmpty);
+
     const mainNavItems = [
       {
         text: 'Blockchain',
@@ -72,7 +84,8 @@ export default function useNavItems(): ReturnType {
       // there should be custom site sections like Stats, Faucet, More, etc but never an 'other'
       // examples https://explorer-edgenet.polygon.technology/ and https://explorer.celo.org/
       // at this stage custom menu items is under development, we will implement it later
-      // { text: 'Other', url: link('other'), icon: gearIcon, isActive: pathname === 'other' },
+      otherNavItems.length > 0 ?
+        { text: 'Other', icon: gearIcon, isActive: otherNavItems.some(item => item.isActive), subItems: otherNavItems } : null,
     ].filter(notEmpty);
 
     const accountNavItems = [
@@ -109,5 +122,5 @@ export default function useNavItems(): ReturnType {
       text: 'My profile', nextRoute: { pathname: '/auth/profile' as const }, icon: profileIcon, isActive: pathname === '/auth/profile', isNewUi: true };
 
     return { mainNavItems, accountNavItems, profileItem };
-  }, [ isMarketplaceFilled, pathname ]);
+  }, [ hasAPIDocs, isMarketplaceFilled, pathname ]);
 }

next.config.js

+const withTM = require('next-transpile-modules')([
+  'react-syntax-highlighter',
+  'swagger-client',
+  'swagger-ui-react',
+]);
 const withRoutes = require('nextjs-routes/config')({
   outDir: 'types',
 });
@@ -7,7 +12,7 @@ const headers = require('./configs/nextjs/headers');
 const redirects = require('./configs/nextjs/redirects');
 const rewrites = require('./configs/nextjs/rewrites');
 
-const moduleExports = {
+const moduleExports = withTM({
   include: path.resolve(__dirname, 'icons'),
   reactStrictMode: true,
   webpack(config, { webpack }) {
@@ -39,6 +44,6 @@ const moduleExports = {
     // otherwise it is impossible to upload large files (over 1Mb)
     bodyParser: false,
   },
-};
+});
 
 module.exports = withRoutes(moduleExports);

package.json

@@ -69,6 +69,7 @@
     "react-identicons": "^1.2.5",
     "react-jazzicon": "^1.0.4",
     "react-scroll": "^1.8.7",
+    "swagger-ui-react": "^4.15.5",
     "use-font-face-observer": "^1.2.1",
     "wagmi": "^0.10.6"
   },
@@ -85,6 +86,7 @@
     "@types/qrcode": "^1.5.0",
     "@types/react": "18.0.9",
     "@types/react-dom": "18.0.5",
+    "@types/swagger-ui-react": "^4.11.0",
     "@types/ws": "^8.5.3",
     "@typescript-eslint/eslint-plugin": "^5.27.0",
     "dotenv-cli": "^6.0.0",
@@ -100,6 +102,7 @@
     "jest-environment-jsdom": "^29.2.1",
     "lint-staged": ">=10",
     "mockdate": "^3.0.5",
+    "next-transpile-modules": "^10.0.0",
     "playwright": "^1.28.0",
     "svgo": "^2.8.0",
     "ts-jest": "^29.0.3",

pages/api-docs.tsx

+import type { NextPage, GetServerSideProps } from 'next';
+import Head from 'next/head';
+import React from 'react';
+
+import appConfig from 'configs/app/config';
+import getNetworkTitle from 'lib/networks/getNetworkTitle';
+import { getServerSideProps as getServerSidePropsBase } from 'lib/next/getServerSideProps';
+import type { Props } from 'lib/next/getServerSideProps';
+import SwaggerUI from 'ui/apiDocs/SwaggerUI';
+import Page from 'ui/shared/Page/Page';
+import PageTitle from 'ui/shared/Page/PageTitle';
+
+const AppsPage: NextPage = () => {
+  const networkTitle = getNetworkTitle();
+
+  return (
+    <Page>
+      <PageTitle text="API Documentation"/>
+      <Head><title>{ `API for the ${ networkTitle }` }</title></Head>
+      <SwaggerUI/>
+    </Page>
+  );
+};
+
+export default AppsPage;
+
+export const getServerSideProps: GetServerSideProps<Props> = async(args) => {
+  if (!appConfig.apiDoc.specUrl) {
+    return {
+      notFound: true,
+    };
+  }
+
+  return getServerSidePropsBase(args);
+};

types/nextjs-routes.d.ts

@@ -16,6 +16,7 @@ declare module "nextjs-routes" {
     | DynamicRoute<"/address/[hash]", { "hash": string }>
     | StaticRoute<"/api/csrf">
     | StaticRoute<"/api/proxy">
+    | StaticRoute<"/api-docs">
     | DynamicRoute<"/apps/[id]", { "id": string }>
     | StaticRoute<"/apps">
     | StaticRoute<"/auth/auth0">

ui/apiDocs/SwaggerUI.tsx

+/* eslint-disable @typescript-eslint/naming-convention */
+const SwaggerUIReact = dynamic(() => import('swagger-ui-react'), {
+  loading: () => <Spinner/>,
+  ssr: false,
+});
+
+import { Box, Spinner, useColorModeValue } from '@chakra-ui/react';
+import dynamic from 'next/dynamic';
+import React from 'react';
+
+import appConfig from 'configs/app/config';
+
+import 'swagger-ui-react/swagger-ui.css';
+
+const DEFAULT_SERVER = 'blockscout.com/poa/core';
+
+const NeverShowInfoPlugin = () => {
+  return {
+    components: {
+      SchemesContainer: () => null,
+      ServersContainer: () => null,
+      InfoContainer: () => null,
+    },
+  };
+};
+
+const SwaggerUI = () => {
+  const swaggerStyle = {
+    '.scheme-container, .opblock-tag': {
+      display: 'none',
+    },
+    '.swagger-ui': {
+      color: useColorModeValue('blackAlpha.800', 'whiteAlpha.800'),
+    },
+    '.swagger-ui .opblock-summary-control:focus': {
+      outline: 'none',
+    },
+    // eslint-disable-next-line max-len
+    '.swagger-ui .opblock .opblock-summary-path, .swagger-ui .opblock .opblock-summary-description, .swagger-ui div, .swagger-ui p, .swagger-ui h5, .swagger-ui .response-col_links, .swagger-ui h4, .swagger-ui table thead tr th, .swagger-ui table thead tr td, .swagger-ui .parameter__name, .swagger-ui .parameter__type, .swagger-ui .response-col_status, .swagger-ui .tab li, .swagger-ui .opblock .opblock-section-header h4': {
+      color: 'unset',
+    },
+    '.swagger-ui input': {
+      color: 'blackAlpha.800',
+    },
+    '.swagger-ui .opblock .opblock-section-header': {
+      background: useColorModeValue('whiteAlpha.800', 'blackAlpha.800'),
+    },
+    '.swagger-ui .response-col_description__inner p, .swagger-ui .parameters-col_description p': {
+      margin: 0,
+    },
+    '.swagger-ui .wrapper': {
+      padding: 0,
+    },
+  };
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const reqInterceptor = React.useCallback((req: any) => {
+    if (!req.loadSpec) {
+      req.url = req.url.replace(DEFAULT_SERVER, appConfig.api.host);
+    }
+    return req;
+  }, []);
+
+  return (
+    <Box sx={ swaggerStyle }>
+      <SwaggerUIReact
+        url={ appConfig.apiDoc.specUrl }
+        plugins={ [ NeverShowInfoPlugin ] }
+        requestInterceptor={ reqInterceptor }
+      />
+    </Box>
+  );
+};
+
+export default SwaggerUI;