Unable to run Docusaurus open api plugin 3.0.0 beta version in Docusaurus 3.1.1 version as mentioned in your documentation.

[RagonPra]

Unable to run Docusaurus open api plugin 3.0.0 beta version in Docusaurus 3.1.1 version as mentioned in your documentation.

[ElliotFriend]

@RagonPra I think the install instructions are just a bit out-of-date for the beta. I went through the setup process this afternoon, and here's what I did differently to get things working.

Installation

I installed the latest version of docusaurus (v3.4 at the moment)

npx create-docusaurus@latest my-website classic --package-manager yarn

I installed the latest beta version of the plugin (v3.0.0-beta.10 at the moment)

yarn add [email protected]
yarn add [email protected]

Changes to your docusaurus.config.js file

The specific error message you're seeing is related to the (outdated) docLayoutComponent config setting in your "classic" preset. Good thing is you don't even need it. (if you do indeed need it for some reason, though unlikely, it would be docRootComponent: "@theme/DocRoot" instead)

        docs: {
          sidebarPath: './sidebars.js',
          // Please change this to your repo.
          // Remove this to remove the "edit this page" links.
          editUrl:
            'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',

-         docLayoutComponent: "@theme/DocPage",
          docItemComponent: "@theme/ApiItem" // derived from docusaurus-theme-openapi-docs
        },

Also, you specified an outputDir for your openapi plugin that's outside the directory structure of your configured docs preset, but you're also trying to use those pages in the classic preset. You can't do both. Easy fix is to put the plugin output somewhere in the docs/ directory.

        'docusaurus-plugin-openapi-docs',
        {
          id: "api", // plugin id
          docsPluginId: "classic", // id of plugin-content-docs or preset for rendering docs
          config: {
            petstore: { // the <id> referenced when running CLI commands
              specPath: "examples/petstore.yaml", // path to OpenAPI spec, URLs supported
-             outputDir: "api/petstore", // output directory for generated files
+             outputDir: "docs/api/petstore", // output directory for generated files
              sidebarOptions: { // optional, instructs plugin to generate sidebar.js
                groupPathsBy: "tag", // group sidebar items by operation "tag"
              },
            },
          }
        },

Generate the api docs

You didn't specify that you actually ran the CLI command to generate the docs from the api plugin. In case you didn't, you would run

yarn docusaurus gen-api-docs all

After that you should be able to build successfully

yarn build

[markandpathak]

I am also facing same issue, I followed the process mentioned by @ElliotFriend. I can compile all mdx. But while building I run into following error:

[ERROR] Client bundle compiled with errors therefore further build is impossible.
Module not found: Error: Can't resolve '@generated/site-storage' in '/mypath/node_modules/docusaurus-theme-openapi-docs/node_modules/@docusaurus/theme-common/lib/utils'
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

Please help.

[ElliotFriend]

@markandpathak I've seen that a few times... I wanna say it was something to do with a newer feature in docusaurus v3.4. I think I fixed it by force upgrading docusaurus and/or react? You could delete node_modules and yarn.lock (at least, I use yarn), and then make sure your package.json file allows for upgrading to docusaurus v3.4, and then running yarn install (again, change that if you're not using yarn). I feel like that worked for me, but I can't exactly remember.

[markandpathak]

@ElliotFriend I tried to upgrade the docusaurus version to 3.4.0, Atleast now that module error is not coming up, but still build process fails. I also created the complete project with
npx [email protected] my-website classic --package-manager yarn --typescript and then followed same steps, same error appears in typescript also.

Now error is:

[ERROR] Error: Unable to build website for locale en.
    at tryToBuildLocale (/mypath/anedya-documentation/anedya-documentation/node_modules/@docusaurus/core/lib/commands/build.js:54:19)
    at async /mypath/anedya-documentation/anedya-documentation/node_modules/@docusaurus/core/lib/commands/build.js:65:9
    at async mapAsyncSequential (/mypath/anedya-documentation/anedya-documentation/node_modules/@docusaurus/utils/lib/jsUtils.js:20:24)
    at async Command.build (/mypath/anedya-documentation/anedya-documentation/node_modules/@docusaurus/core/lib/commands/build.js:63:5) {
  [cause]: Error: Docusaurus static site generation failed for 22 paths:
  - "/docs/api/petstore/add-pet"
  - "/docs/api/petstore/create-user"
  - "/docs/api/petstore/create-users-with-array-input"
  - "/docs/api/petstore/create-users-with-list-input"
  - "/docs/api/petstore/delete-order"
  - "/docs/api/petstore/delete-pet"
  - "/docs/api/petstore/delete-user"
  - "/docs/api/petstore/find-pets-by-status"
  - "/docs/api/petstore/find-pets-by-tags"
  - "/docs/api/petstore/get-inventory"
  - "/docs/api/petstore/get-order-by-id"
  - "/docs/api/petstore/get-pet-by-id"
  - "/docs/api/petstore/get-user-by-name"
  - "/docs/api/petstore/login-user"
  - "/docs/api/petstore/logout-user"
  - "/docs/api/petstore/new-pet"
  - "/docs/api/petstore/place-order"
  - "/docs/api/petstore/subscribe-to-the-store-events"
  - "/docs/api/petstore/update-pet"
  - "/docs/api/petstore/update-pet-with-form"
  - "/docs/api/petstore/update-user"
  - "/docs/api/petstore/upload-file"
      at generateStaticFiles (/mypath/anedya-documentation/anedya-documentation/node_modules/@docusaurus/core/lib/ssg.js:85:15)
      at async executeSSG (/mypath/anedya-documentation/anedya-documentation/node_modules/@docusaurus/core/lib/commands/build.js:175:23)
      ... 4 lines matching cause stack trace ...
      at async Command.build (/mypath/anedya-documentation/anedya-documentation/node_modules/@docusaurus/core/lib/commands/build.js:63:5) {
    [cause]: AggregateError
        at generateStaticFiles (/mypath/anedya-documentation/anedya-documentation/node_modules/@docusaurus/core/lib/ssg.js:86:20)
        at async executeSSG (/mypath/anedya-documentation/anedya-documentation/node_modules/@docusaurus/core/lib/commands/build.js:175:23)
        at async buildLocale (/mypath/anedya-documentation/anedya-documentation/node_modules/@docusaurus/core/lib/commands/build.js:135:31)
        at async tryToBuildLocale (/mypath/anedya-documentation/anedya-documentation/node_modules/@docusaurus/core/lib/commands/build.js:47:13)
        at async /mypath/anedya-documentation/anedya-documentation/node_modules/@docusaurus/core/lib/commands/build.js:65:9
        at async mapAsyncSequential (/mypath/anedya-documentation/anedya-documentation/node_modules/@docusaurus/utils/lib/jsUtils.js:20:24)
        at async Command.build (/mypath/anedya-documentation/anedya-documentation/node_modules/@docusaurus/core/lib/commands/build.js:63:5) {
      [errors]: [
        Error: Can't render static file for pathname "/docs/api/petstore/add-pet"
            at generateStaticFile (/mypath/anedya-documentation/anedya-documentation/node_modules/@docusaurus/core/lib/ssg.js:119:15)
            at runNextTicks (node:internal/process/task_queues:60:5)
            at process.processImmediate (node:internal/timers:447:9)
            at async /mypath/anedya-documentation/anedya-documentation/node_modules/p-map/index.js:57:22 {
          [cause]: TypeError: Cannot read properties of null (reading 'store')
              at useSelector (server.bundle.js:42604:34)
              at MethodEndpoint (server.bundle.js:27568:773)
              at Uc (server.bundle.js:40345:44)
              at Xc (server.bundle.js:40347:253)
              at Z (server.bundle.js:40353:89)
              at Yc (server.bundle.js:40356:98)
              at $c (server.bundle.js:40355:140)
              at Z (server.bundle.js:40353:345)
              at Xc (server.bundle.js:40348:476)
              at Z (server.bundle.js:40353:89)
        },

Actual error is quite long, I have included error message for one page only, this repeats for all API pages.
[cause]: TypeError: Cannot read properties of null (reading 'store') is common in errors for all pages. Maybe it has something to do with localization settings. I also tried commenting out i18n part from the config, but that didn't work. Maybe you can guide me in this.

For your reference:

// @ts-check
// `@type` JSDoc annotations allow editor autocompletion and type checking
// (when paired with `@ts-check`).
// There are various equivalent ways to declare your Docusaurus config.
// See: https://docusaurus.io/docs/api/docusaurus-config

import {themes as prismThemes} from 'prism-react-renderer';

/** @type {import('@docusaurus/types').Config} */
const config = {
  title: 'My Site',
  tagline: 'Dinosaurs are cool',
  favicon: 'img/favicon.ico',

  // Set the production url of your site here
  url: 'https://your-docusaurus-site.example.com',
  // Set the /<baseUrl>/ pathname under which your site is served
  // For GitHub pages deployment, it is often '/<projectName>/'
  baseUrl: '/',

  // GitHub pages deployment config.
  // If you aren't using GitHub pages, you don't need these.
  organizationName: 'facebook', // Usually your GitHub org/user name.
  projectName: 'docusaurus', // Usually your repo name.

  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',

  // Even if you don't use internationalization, you can use this field to set
  // useful metadata like html lang. For example, if your site is Chinese, you
  // may want to replace "en" with "zh-Hans".
  i18n: {
    defaultLocale: 'en',
    locales: ['en'],
  },

  presets: [
    [
      'classic',
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        docs: {
          sidebarPath: './sidebars.js',
          // Please change this to your repo.
          // Remove this to remove the "edit this page" links.
          editUrl:
            'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
        },
        blog: {
          showReadingTime: true,
          // Please change this to your repo.
          // Remove this to remove the "edit this page" links.
          editUrl:
            'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
        },
        theme: {
          customCss: './src/css/custom.css',
        },
      }),
    ],
  ],

  themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    ({
      // Replace with your project's social card
      image: 'img/docusaurus-social-card.jpg',
      navbar: {
        title: 'My Site',
        logo: {
          alt: 'My Site Logo',
          src: 'img/logo.svg',
        },
        items: [
          {
            type: 'docSidebar',
            sidebarId: 'tutorialSidebar',
            position: 'left',
            label: 'Tutorial',
          },
          {to: '/blog', label: 'Blog', position: 'left'},
          {
            href: 'https://github.com/facebook/docusaurus',
            label: 'GitHub',
            position: 'right',
          },
        ],
      },
      footer: {
        style: 'dark',
        links: [
          {
            title: 'Docs',
            items: [
              {
                label: 'Tutorial',
                to: '/docs/intro',
              },
            ],
          },
          {
            title: 'Community',
            items: [
              {
                label: 'Stack Overflow',
                href: 'https://stackoverflow.com/questions/tagged/docusaurus',
              },
              {
                label: 'Discord',
                href: 'https://discordapp.com/invite/docusaurus',
              },
              {
                label: 'Twitter',
                href: 'https://twitter.com/docusaurus',
              },
            ],
          },
          {
            title: 'More',
            items: [
              {
                label: 'Blog',
                to: '/blog',
              },
              {
                label: 'GitHub',
                href: 'https://github.com/facebook/docusaurus',
              },
            ],
          },
        ],
        copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,
      },
      prism: {
        theme: prismThemes.github,
        darkTheme: prismThemes.dracula,
      },
    }),

    plugins: [
      [
        'docusaurus-plugin-openapi-docs',
        {
          id: "api", // plugin id
          docsPluginId: "classic", // id of plugin-content-docs or preset for rendering docs
          config: {
            petstore: { // the <id> referenced when running CLI commands
              specPath: "examples/petstore.yaml", // path to OpenAPI spec, URLs supported
              outputDir: "docs/api/petstore", // output directory for generated files
              sidebarOptions: { // optional, instructs plugin to generate sidebar.js
                groupPathsBy: "tag", // group sidebar items by operation "tag"
              },
            },
          }
        },
      ]
    ],

    themes: ["docusaurus-theme-openapi-docs"], // export theme components
};

export default config;

Package.json file:

{
  "name": "anedya-documentation",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "docusaurus": "docusaurus",
    "start": "docusaurus start",
    "build": "docusaurus build",
    "swizzle": "docusaurus swizzle",
    "deploy": "docusaurus deploy",
    "clear": "docusaurus clear",
    "serve": "docusaurus serve",
    "write-translations": "docusaurus write-translations",
    "write-heading-ids": "docusaurus write-heading-ids"
  },
  "dependencies": {
    "@docusaurus/core": "3.4.0",
    "@docusaurus/preset-classic": "3.4.0",
    "@mdx-js/react": "^3.0.0",
    "clsx": "^2.0.0",
    "docusaurus-plugin-openapi-docs": "3.0.0-beta.10",
    "docusaurus-theme-openapi-docs": "3.0.0-beta.10",
    "prism-react-renderer": "^2.3.0",
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  },
  "devDependencies": {
    "@docusaurus/module-type-aliases": "3.4.0",
    "@docusaurus/types": "3.4.0"
  },
  "browserslist": {
    "production": [
      ">0.5%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 3 chrome version",
      "last 3 firefox version",
      "last 5 safari version"
    ]
  },
  "engines": {
    "node": ">=18.0"
  }
}

[markandpathak]

@ElliotFriend Any update on the issue? How to mitigate this error?

[SirPhemmiey]

@markandpathak i'm also having the same issue. Have you found a way around it?

[ElliotFriend]

@markandpathak and @SirPhemmiey I think it's a problem with your classic preset config. The docs config on the preset needs to contain this property: docItemComponent: "@theme/ApiItem". Like the one here.

Following the same steps in that comment this morning, I could successfully yarn build a clean installation. Without that docItemComponent I was seeing the same error, too.

Hope that helps!

[markandpathak]

@ElliotFriend You saved the day! It works. Thank you very much for the help. I hope these instructions get added to the main readme documentation for other users' benefit.

[sserrata]

As a reminder, we will happily accept PRs for changes such as these, especially if they'll help others avoid the same pitfalls.

[sserrata]

Will update documentation coinciding with next stable v2/v3 releases