feat: add support for passing spec directly (#424)

Version of #422 with bare minimum changes while still supporting the feature

feat: minimally add spec option to all components and update docs

---------

Co-authored-by: Léo MIEULET <[email protected]>

Author: rohit-gohri

.changeset/ninety-eagles-call.md

@@ -0,0 +1,9 @@
+---
+"docusaurus-plugin-redoc": minor
+"docusaurus-theme-redoc": minor
+"redocusaurus": patch
+---
+
+feat: add support for passing `spec` directly to all components
+
+Update docs to add various missing things.

package.json

@@ -80,5 +80,8 @@
     "printWidth": 80,
     "tabWidth": 2
   },
-  "packageManager": "[email protected]"
+  "packageManager": "[email protected]",
+  "volta": {
+    "node": "18.12.0"
+  }
 }

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

@@ -42,10 +42,18 @@ export default function redocPlugin(
 }> {
   const { baseUrl } = context.siteConfig;
   const options: PluginOptionsWithDefault = { ...DEFAULT_OPTIONS, ...opts };
-  const { debug, spec, url: downloadUrl, config, themeId, normalizeUrl: normalizeDownloadUrl } = options;
+  const {
+    debug,
+    spec,
+    url: downloadUrl,
+    config,
+    themeId,
+    normalizeUrl: normalizeDownloadUrl,
+  } = options;
 
   let url = downloadUrl;
   const isSpecFile = fs.existsSync(spec);
+
   const fileName = path.join(
     'redocusaurus',
     `${options.id || 'api-spec'}.yaml`,

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

@@ -1,11 +1,11 @@
 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 specProps = useSpecData(id);
+const ApiDocMdx: React.FC<MdxProps> = ({ id, spec }: MdxProps): JSX.Element => {
+  const specProps = useSpecData(id, spec);
   const optionsOverrides = useMemo(() => {
     return {
       theme: {

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

@@ -1,21 +1,22 @@
 import React, { useEffect } from 'react';
+import useSpecData from '@theme/useSpecData';
 import clsx from 'clsx';
 import { ThemeProvider } from 'styled-components';
 import '../../global';
 import { Operation, OperationModel, Section } from 'redoc';
 import { useSpec } from '../../utils/useSpec';
-import { useSpecData } from '../useSpecData';
-import type { ApiOperationProps as Props } from '../../types/common';
+import type { ApiOperationProps } from '../../types/common';
 import '../Redoc/styles.css';
 import './styles.css';
 
-const ApiOperation: React.FC<Props> = ({
+const ApiOperation: React.FC<ApiOperationProps> = ({
   id,
-  example,
+  spec,
+  example = false,
   pointer,
   ...rest
-}: Props): JSX.Element => {
-  const specProps = useSpecData(id);
+}: ApiOperationProps): JSX.Element => {
+  const specProps = useSpecData(id, spec);
   const { store } = useSpec(specProps);
 
   // The # at the start is not included
@@ -56,8 +57,4 @@ const ApiOperation: React.FC<Props> = ({
   );
 };
 
-ApiOperation.defaultProps = {
-  example: false,
-};
-
 export default ApiOperation;

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

@@ -5,17 +5,19 @@ import '../../global';
 import { SchemaDefinition } from 'redoc';
 import { useSpec } from '../../utils/useSpec';
 import { useSpecData } from '../useSpecData';
-import type { ApiSchemaProps as Props } from '../../types/common';
+import type { ApiSchemaProps } from '../../types/common';
 import '../Redoc/styles.css';
 import './styles.css';
 
-const ApiSchema: React.FC<Props> = ({
+const ApiSchema: React.FC<ApiSchemaProps> = ({
   id,
-  example,
+  spec,
   pointer,
+  showExample = false,
+  example = showExample,
   ...rest
-}: Props): JSX.Element => {
-  const specProps = useSpecData(id);
+}: ApiSchemaProps): JSX.Element => {
+  const specProps = useSpecData(id, spec);
   const { store } = useSpec(specProps);
 
   useEffect(() => {
@@ -38,15 +40,12 @@ const ApiSchema: React.FC<Props> = ({
           parser={store.spec.parser}
           options={store.options}
           schemaRef={pointer}
+          showExample={example}
           {...rest}
         />
       </div>
     </ThemeProvider>
   );
 };
 
-ApiSchema.defaultProps = {
-  example: false,
-};
-
 export default ApiSchema;

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

@@ -1,37 +1,50 @@
 import React from 'react';
+import useSpecData from '@theme/useSpecData';
 import clsx from 'clsx';
 import '../../global';
-import { RedocStandalone, RedocRawOptions } from 'redoc';
-import type { SpecProps } from '../../types/common';
+import { RedocStandalone } from 'redoc';
+import type { RedocProps } from '../../types/common';
 import { useSpecOptions } from '../../utils/useSpecOptions';
 import './styles.css';
 import ServerRedoc from './ServerRedoc';
 
+const isDevMode = process.env.NODE_ENV === 'development';
+
 /*!
  * Redocusaurus
  * https://redocusaurus.vercel.app/
- * (c) 2024 Rohit Gohri
+ * (c) 2025 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(initProps: RedocProps): JSX.Element {
+  // eslint-disable-next-line react/destructuring-assignment
+  const specProps = useSpecData(initProps.id, initProps.spec);
+  const finalProps = {
+    ...specProps,
+    ...initProps,
+  };
+
+  const {
+    spec,
+    className,
+    isSpecFile = spec != null,
+    url,
+    themeId,
+    optionsOverrides,
+  } = finalProps;
   const { options } = useSpecOptions(themeId, optionsOverrides);
-  const isDevMode = process.env.NODE_ENV === 'development';
 
-  if ((isDevMode && isSpecFile === false) || !spec) {
-    return (
-      <div className={clsx(['redocusaurus', className])}>
-        <RedocStandalone specUrl={url} options={options} />
-      </div>
-    );
+  const enableServerRendering = spec != null && (!isDevMode || isSpecFile);
+
+  if (enableServerRendering) {
+    return <ServerRedoc {...finalProps} spec={spec} />;
   }
 
-  return <ServerRedoc {...props} spec={spec} />;
+  return (
+    <div className={clsx(['redocusaurus', className])}>
+      <RedocStandalone specUrl={url} options={options} />
+    </div>
+  );
 }
 
 export default Redoc;

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

@@ -1,32 +1,28 @@
 import React from 'react';
+import useBrokenLinks, { BrokenLinks } from '@docusaurus/useBrokenLinks';
 import clsx from 'clsx';
 import '../../global';
-import { IMenuItem, Redoc as RedocComponent, RedocRawOptions } from 'redoc';
-import type { SpecProps } from '../../types/common';
+import { IMenuItem, Redoc as RedocComponent } from 'redoc';
+import type { ServerRedocProps } from '../../types/common';
 import { useSpec } from '../../utils/useSpec';
-import useBrokenLinks, { BrokenLinks } from '@docusaurus/useBrokenLinks';
 import { ServerStyles } from './Styles';
 import './styles.css';
 
 /*!
  * Redocusaurus
  * https://redocusaurus.vercel.app/
- * (c) 2024 Rohit Gohri
+ * (c) 2025 Rohit Gohri
  * Released under the MIT License
  */
-function ServerRedoc(
-  props: SpecProps & {
-    className?: string;
-    optionsOverrides?: RedocRawOptions;
-  },
-): JSX.Element {
+function ServerRedoc(props: ServerRedocProps): JSX.Element {
   const { className, optionsOverrides, ...specProps } = props;
   const { store, darkThemeOptions, lightThemeOptions, hasLogo } = useSpec(
     specProps,
     optionsOverrides,
   );
 
   const collector = useBrokenLinks();
+  // eslint-disable-next-line @typescript-eslint/no-use-before-define
   collectMenuItemAnchors(collector, store.menu.items);
 
   return (
@@ -49,23 +45,27 @@ function ServerRedoc(
   );
 }
 
-function collectMenuItemAnchors(collector: BrokenLinks, menuItems: IMenuItem[], parentAnchor = "") {
+function collectMenuItemAnchors(
+  collector: BrokenLinks,
+  menuItems: IMenuItem[],
+  parentAnchor = '',
+) {
   menuItems.forEach((menuItem) => {
     // Register anchor for menu item
     collector.collectAnchor(menuItem.id);
 
     // If this is a child menu item, register a shortened anchor as well
     // This may not be necessary in all cases, but definitely needed for
     // menuItems of the form `tag/<Tag ID>/operation/<Operation ID>`.
-    if (parentAnchor != "") {
-      const childAnchor = menuItem.id.replace(`${parentAnchor}/`, "")
+    if (parentAnchor != '') {
+      const childAnchor = menuItem.id.replace(`${parentAnchor}/`, '');
       collector.collectAnchor(childAnchor);
     }
 
     if (menuItem.items.length > 0) {
-      collectMenuItemAnchors(collector, menuItem.items, menuItem.id)
+      collectMenuItemAnchors(collector, menuItem.items, menuItem.id);
     }
-  })
+  });
 }
 
 export default ServerRedoc;

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

@@ -31,15 +31,17 @@ 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 = {
+  specProps: SpecProps;
+  lightThemeOptions: RedocRawOptions;
+  darkThemeOptions: RedocRawOptions;
+};
+
 export function ServerStyles({
   specProps,
   lightThemeOptions,
   darkThemeOptions,
-}: {
-  specProps: SpecProps;
-  lightThemeOptions: RedocRawOptions;
-  darkThemeOptions: RedocRawOptions;
-}) {
+}: ServerStylesProps) {
   const absoluteUrl = useBaseUrl(specProps.url, { absolute: true });
   const fullUrl = specProps.normalizeUrl ? absoluteUrl : specProps.url;
 

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>;
 }