Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
RagonPra opened this issue Jun 3, 2024 · 10 comments
Labels
documentation Improvements or additions to documentation

Comments

@RagonPra
Copy link

RagonPra commented Jun 3, 2024

I have installed a demo site from docusaurus command:

npx create-docusaurus@3.1.1 my-website classic

Opened the project folder command terminal and executed following commands:

yarn add docusaurus-plugin-openapi-docs@3.0.0-beta.1
yarn add docusaurus-theme-openapi-docs@3.0.0-beta.1

I have modified my docusaurus config file as follows:

// @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/',

          docLayoutComponent: "@theme/DocPage",
          docItemComponent: "@theme/ApiItem" // derived from docusaurus-theme-openapi-docs
        },
        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: "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;

Modified my package.json file as follows:

{
  "name": "my-website",
  "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.1.1",
    "@docusaurus/preset-classic": "3.1.1",
    "@mdx-js/react": "^3.0.0",
    "clsx": "^2.0.0",
    "docusaurus-plugin-openapi-docs": "3.0.0-beta.1",
    "docusaurus-theme-openapi-docs": "3.0.0-beta.1",
    "prism-react-renderer": "^2.3.0",
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  },
  "devDependencies": {
    "@docusaurus/module-type-aliases": "3.1.1",
    "@docusaurus/types": "3.1.1"
  },
  "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"
  }
}

When i ran npm run build command, i am getting this error:

[INFO] [en] Creating an optimized production build...

Error: Unable to build website for locale en.
    at tryToBuildLocale (/Users/mallavenkataraghunadh/my-website/node_modules/@docusaurus/core/lib/commands/build.js:55:19)
    at async mapAsyncSequential (/Users/mallavenkataraghunadh/my-website/node_modules/@docusaurus/utils/lib/jsUtils.js:44:24)
    at async Command.build (/Users/mallavenkataraghunadh/my-website/node_modules/@docusaurus/core/lib/commands/build.js:82:21) {
  [cause]: [Error [ValidationError]: "docLayoutComponent" is not allowed] {
    _original: {
      sidebarPath: './sidebars.js',
      editUrl: 'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
      docLayoutComponent: '@theme/DocPage',
      docItemComponent: '@theme/ApiItem'
    },
    details: [ [Object] ]
  }
}

[INFO] Docusaurus version: 3.1.1
Node version: v22.1.0

How to fix this issue?

@RagonPra RagonPra added the bug Something isn't working label Jun 3, 2024
@ElliotFriend
Copy link
Contributor

ElliotFriend commented Jun 6, 2024

@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 docusaurus-plugin-openapi-docs@3.0.0-beta.10
yarn add docusaurus-theme-openapi-docs@3.0.0-beta.10

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
Copy link

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
Copy link
Contributor

@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
Copy link

@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 create-docusaurus@3.4.0 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
Copy link

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

@SirPhemmiey
Copy link

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

@ElliotFriend
Copy link
Contributor

@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
Copy link

@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
Copy link
Member

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

@sserrata sserrata added documentation Improvements or additions to documentation help wanted Extra attention is needed and we are accepting pull requests from anyone willing to take this on. and removed bug Something isn't working help wanted Extra attention is needed and we are accepting pull requests from anyone willing to take this on. labels Jun 24, 2024
@sserrata
Copy link
Member

Will update documentation coinciding with next stable v2/v3 releases

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

No branches or pull requests

5 participants