Improve types, doc, allow spec on ApiSchema + various changes

Author: Léo MIEULET

package.json

@@ -80,5 +80,8 @@
     "printWidth": 80,
     "tabWidth": 2
   },
-  "packageManager": "yarn@4.0.1"
+  "packageManager": "yarn@4.0.1",
+  "volta": {
+    "node": "18.12.0"
+  }
 }

packages/docusaurus-plugin-redoc/src/index.ts

@@ -24,7 +24,7 @@ import {
   PluginDirectUsageOptions,
   DEFAULT_OPTIONS,
 } from './options';
-import type { SpecProps, ApiDocProps } from './types/common';
+import type { SpecDataResult, ApiDocProps } from './types/common';
 import { loadSpecWithConfig } from './loadSpec';
 import { loadRedoclyConfig } from './loadRedoclyConfig';
 
@@ -45,12 +45,13 @@ export default function redocPlugin(
   const { debug, spec, url: downloadUrl, config, themeId } = options;
 
   let url = downloadUrl;
-  const isSpecFile = fs.existsSync(spec);
+  const isExternalUrl = !!url;
+
   const fileName = path.join(
     'redocusaurus',
     `${options.id || 'api-spec'}.yaml`,
   );
-  let filesToWatch: string[] = isSpecFile ? [path.resolve(spec)] : [];
+  let filesToWatch: string[] = !isExternalUrl ? [path.resolve(spec)] : [];
 
   if (debug) {
     console.error('[REDOCUSAURUS_PLUGIN] Opts Input:', opts);
@@ -67,7 +68,7 @@ export default function redocPlugin(
 
       let bundledSpec: Document, problems: NormalizedProblem[];
 
-      if (!isSpecFile) {
+      if (isExternalUrl) {
         // If spec is a remote url then add it as download url also as a default
         url = url || spec;
         if (debug) {
@@ -123,10 +124,9 @@ export default function redocPlugin(
         throw new Error(`[Redocusaurus] Spec could not be parsed: ${spec}`);
       }
 
-      const data: SpecProps = {
-        url,
+      const data: SpecDataResult = {
+        downloadSpecUrl: url,
         themeId,
-        isSpecFile,
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         spec: content.converted as any,
       };
@@ -165,7 +165,7 @@ export default function redocPlugin(
       }
     },
     async postBuild({ content }) {
-      if (!isSpecFile || downloadUrl) {
+      if (isExternalUrl || downloadUrl) {
         return;
       }
       // Create a static file from bundled spec

packages/docusaurus-theme-redoc/src/theme/ApiDocMdx/ApiDocMdx.tsx

@@ -1,10 +1,10 @@
 import React, { useMemo } from 'react';
 import Redoc from '@theme/Redoc';
 import useSpecData from '@theme/useSpecData';
-import type { MdxProps as Props } from '../../types/common';
+import type { MdxProps } from '../../types/common';
 import '../ApiSchema/styles.css';
 
-const ApiDocMdx: React.FC<Props> = ({ id }: Props): JSX.Element => {
+const ApiDocMdx: React.FC<MdxProps> = ({ id }: MdxProps): JSX.Element => {
   const specProps = useSpecData(id);
   const optionsOverrides = useMemo(() => {
     return {

packages/docusaurus-theme-redoc/src/theme/ApiSchema/ApiSchema.tsx

@@ -3,20 +3,27 @@ import clsx from 'clsx';
 import { ThemeProvider } from 'styled-components';
 import '../../global';
 import { SchemaDefinition } from 'redoc';
-import { useSpec } from '../../utils/useSpec';
-import { useSpecData } from '../useSpecData';
-import type { ApiSchemaProps as Props } from '../../types/common';
+import useSpec from '@theme/useSpec';
 import '../Redoc/styles.css';
 import './styles.css';
 
-const ApiSchema: React.FC<Props> = ({
-  id,
-  example,
+const ApiSchema: React.FC<ApiSchemaProps> = ({
+  showExample,
   pointer,
+  id,
+  themeId,
+  spec,
+  optionsOverrides,
   ...rest
-}: Props): JSX.Element => {
-  const specProps = useSpecData(id);
-  const { store } = useSpec(specProps);
+}: ApiSchemaProps): JSX.Element => {
+  const { store } = useSpec(
+    {
+      id,
+      themeId,
+      spec,
+    },
+    optionsOverrides,
+  );
 
   useEffect(() => {
     /**
@@ -31,13 +38,14 @@ const ApiSchema: React.FC<Props> = ({
         className={clsx([
           'redocusaurus',
           'redocusaurus-schema',
-          example ? null : 'hide-example',
+          showExample ? null : 'hide-example',
         ])}
       >
         <SchemaDefinition
           parser={store.spec.parser}
           options={store.options}
           schemaRef={pointer}
+          showExample={showExample}
           {...rest}
         />
       </div>
@@ -46,7 +54,7 @@ const ApiSchema: React.FC<Props> = ({
 };
 
 ApiSchema.defaultProps = {
-  example: false,
+  showExample: false,
 };
 
 export default ApiSchema;

packages/docusaurus-theme-redoc/src/theme/Redoc/Redoc.tsx

@@ -1,9 +1,8 @@
 import React from 'react';
 import clsx from 'clsx';
 import '../../global';
-import { RedocStandalone, RedocRawOptions } from 'redoc';
-import type { SpecProps } from '../../types/common';
-import { useSpecOptions } from '../../utils/useSpecOptions';
+import { RedocStandalone } from 'redoc';
+import useSpecOptions from '@theme/useSpecOptions';
 import './styles.css';
 import ServerRedoc from './ServerRedoc';
 
@@ -13,25 +12,19 @@ import ServerRedoc from './ServerRedoc';
  * (c) 2024 Rohit Gohri
  * Released under the MIT License
  */
-function Redoc(
-  props: Partial<SpecProps> & {
-    className?: string;
-    optionsOverrides?: RedocRawOptions;
-  },
-): JSX.Element {
-  const { className, optionsOverrides, spec, url, themeId, isSpecFile } = props;
+function Redoc(props: RedocProps): JSX.Element {
+  const { className, optionsOverrides, url, themeId } = props;
   const { options } = useSpecOptions(themeId, optionsOverrides);
-  const isDevMode = process.env.NODE_ENV === 'development';
 
-  if ((isDevMode && isSpecFile === false) || !spec) {
+  if (url) {
     return (
       <div className={clsx(['redocusaurus', className])}>
         <RedocStandalone specUrl={url} options={options} />
       </div>
     );
   }
 
-  return <ServerRedoc {...props} spec={spec} />;
+  return <ServerRedoc {...props} />;
 }
 
 export default Redoc;

packages/docusaurus-theme-redoc/src/theme/Redoc/ServerRedoc.tsx

@@ -1,9 +1,8 @@
 import React from 'react';
 import clsx from 'clsx';
 import '../../global';
-import { Redoc as RedocComponent, RedocRawOptions } from 'redoc';
-import type { SpecProps } from '../../types/common';
-import { useSpec } from '../../utils/useSpec';
+import { Redoc as RedocComponent } from 'redoc';
+import useSpec from '@theme/useSpec';
 import { ServerStyles } from './Styles';
 import './styles.css';
 
@@ -13,22 +12,23 @@ import './styles.css';
  * (c) 2024 Rohit Gohri
  * Released under the MIT License
  */
-function ServerRedoc(
-  props: SpecProps & {
-    className?: string;
-    optionsOverrides?: RedocRawOptions;
-  },
-): JSX.Element {
-  const { className, optionsOverrides, ...specProps } = props;
-  const { store, darkThemeOptions, lightThemeOptions, hasLogo } = useSpec(
-    specProps,
+function ServerRedoc(props: RedocProps): JSX.Element {
+  const { className, optionsOverrides, id, themeId, downloadSpecUrl } = props;
+  const { store, spec, darkThemeOptions, lightThemeOptions, hasLogo } = useSpec(
+    {
+      spec: props.spec,
+      themeId,
+      downloadSpecUrl,
+      id,
+    },
     optionsOverrides,
   );
 
   return (
     <>
       <ServerStyles
-        specProps={specProps}
+        spec={spec}
+        url={downloadSpecUrl}
         lightThemeOptions={lightThemeOptions}
         darkThemeOptions={darkThemeOptions}
       />

packages/docusaurus-theme-redoc/src/theme/Redoc/ServerStyles.tsx

@@ -2,6 +2,7 @@ import React from 'react';
 import '../../global';
 import useBaseUrl from '@docusaurus/useBaseUrl';
 import { AppStore, Redoc, RedocRawOptions } from 'redoc';
+import type { OpenAPISpec } from 'redoc/typings/types';
 // eslint-disable-next-line import/no-extraneous-dependencies
 import { renderToString } from 'react-dom/server';
 import { ServerStyleSheet } from 'styled-components';
@@ -31,24 +32,28 @@ const renderCss = function (store: AppStore): string {
 const LIGHT_MODE_PREFIX = "html:not([data-theme='dark'])";
 const DARK_MODE_PREFIX = "html([data-theme='dark'])";
 
+export type ServerStylesProps = {
+  spec: OpenAPISpec;
+  url?: string;
+  lightThemeOptions: RedocRawOptions;
+  darkThemeOptions: RedocRawOptions;
+};
+
 export function ServerStyles({
-  specProps,
+  spec,
+  url,
   lightThemeOptions,
   darkThemeOptions,
-}: {
-  specProps: SpecProps;
-  lightThemeOptions: RedocRawOptions;
-  darkThemeOptions: RedocRawOptions;
-}) {
-  const fullUrl = useBaseUrl(specProps.url, { absolute: true });
+}: ServerStylesProps) {
+  const fullUrl = useBaseUrl(url, { absolute: true });
 
   const lightCss = prefixCssSelectors(
-    renderCss(new AppStore(specProps.spec, fullUrl, lightThemeOptions)),
+    renderCss(new AppStore(spec, fullUrl, lightThemeOptions)),
     LIGHT_MODE_PREFIX,
   );
 
   const darkCss = prefixCssSelectors(
-    renderCss(new AppStore(specProps.spec, fullUrl, darkThemeOptions)),
+    renderCss(new AppStore(spec, fullUrl, darkThemeOptions)),
     DARK_MODE_PREFIX,
   );
 

packages/docusaurus-theme-redoc/src/theme/Redoc/Styles.tsx

@@ -1,15 +1,11 @@
 import React from 'react';
 import '../../global';
-import type { RedocRawOptions } from 'redoc';
+import type { ServerStylesProps } from './ServerStyles';
 
 /**
  * Don't hydrate/replace server styles
  * @see https://github.com/facebook/react/issues/10923#issuecomment-338715787
  */
-export function ServerStyles(_props: {
-  specProps: SpecProps;
-  lightThemeOptions: RedocRawOptions;
-  darkThemeOptions: RedocRawOptions;
-}) {
+export function ServerStyles(_props: ServerStylesProps) {
   return <div className="redocusaurus-styles"></div>;
 }

packages/docusaurus-theme-redoc/src/theme/useSpec/index.ts

@@ -0,0 +1,3 @@
+import { useSpec } from './useSpec';
+
+export default useSpec;

…usaurus-theme-redoc/src/utils/useSpec.ts …theme-redoc/src/theme/useSpec/useSpec.tspackages/docusaurus-theme-redoc/src/utils/useSpec.ts renamed to packages/docusaurus-theme-redoc/src/theme/useSpec/useSpec.ts packages/docusaurus-theme-redoc/src/utils/useSpec.ts renamed to packages/docusaurus-theme-redoc/src/theme/useSpec/useSpec.ts

@@ -2,10 +2,10 @@ import { useMemo, useEffect } from 'react';
 import useBaseUrl from '@docusaurus/useBaseUrl';
 import useIsBrowser from '@docusaurus/useIsBrowser';
 import { useColorMode } from '@docusaurus/theme-common';
-import '../global';
+import useSpecData from '@theme/useSpecData';
+import useSpecOptions from '@theme/useSpecOptions';
+import '../../global';
 import { AppStore, RedocRawOptions } from 'redoc';
-import type { SpecProps } from '../types/common';
-import { useSpecOptions } from './useSpecOptions';
 
 // the current store singleton in the app's instance
 let currentStore: AppStore | null = null;
@@ -17,27 +17,37 @@ let currentStore: AppStore | null = null;
  * Released under the MIT License
  */
 export function useSpec(
-  { spec, url, themeId }: SpecProps,
+  specInfo: SpecProps,
   optionsOverrides?: RedocRawOptions,
-) {
+): SpecResult {
+  const { spec, downloadSpecUrl, themeId } = useSpecData(
+    specInfo.id,
+    specInfo.spec,
+    specInfo.themeId,
+  );
   const specOptions = useSpecOptions(themeId, optionsOverrides);
-  const fullUrl = useBaseUrl(url, { absolute: true });
+  // build download URL by using downloadSpecUrl, fallback to useSpecData result
+  const fullDownloadSpecUrl = useBaseUrl(
+    specInfo.downloadSpecUrl || downloadSpecUrl,
+    { absolute: true },
+  );
   const isBrowser = useIsBrowser();
   const isDarkTheme = useColorMode().colorMode === 'dark';
 
   const result = useMemo(() => {
     if (currentStore !== null && isBrowser) {
       currentStore.dispose();
     }
-    currentStore = new AppStore(spec, fullUrl, specOptions.options);
+    currentStore = new AppStore(spec, fullDownloadSpecUrl, specOptions.options);
 
     return {
       ...specOptions,
       // @ts-expect-error extra prop
       hasLogo: !!spec.info?.['x-logo'],
       store: currentStore,
+      spec,
     };
-  }, [isBrowser, spec, fullUrl, specOptions]);
+  }, [isBrowser, spec, fullDownloadSpecUrl, specOptions]);
 
   useEffect(() => {
     // to ensure that menu is properly loaded when theme gets changed