Getting Error: Cannot find module 'docusaurus-plugin-openapi' when trying to use as plugin

[Anthony-Gaudino]

I'm following the instructions to update to 0.2.2. I installed docusaurus-preset-openapi and uninstalled docusaurus-plugin-openapi as I understood that docusaurus-preset-openapi already includes the plugin.

Just using the preset it works, but when I try to have multiple OpenApi definitions where I need to add a plugin entry I get an Error: Cannot find module 'docusaurus-plugin-openapi'.

My package.json:

{
  "name": "docs",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "backoffice-rest-api": "openapi-comment-parser ../source/server/rt backoffice_rest_api.json",
    "kiosk-rest-api": "openapi-comment-parser ../source/server/rtkiosk kiosk_rest_api.json",
    "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",
    "watch": "nodemon -e yaml,js --exec \"openapi-comment-parser src docs/openapi.json && node src/index.js\"",
    "api": "openapi-comment-parser test openapi.json"
  },
  "dependencies": {
    "@docusaurus/core": "2.0.0-beta.9",
    "@docusaurus/preset-classic": "2.0.0-beta.9",
    "@mdx-js/react": "^1.6.21",
    "@svgr/webpack": "^5.5.0",
    "clsx": "^1.1.1",
    "docusaurus-dmd-plugin": "file:../docusaurus-dmd-plugin",
    "docusaurus-preset-openapi": "^0.2.2",
    "file-loader": "^6.2.0",
    "prism-react-renderer": "^1.2.1",
    "react": "^17.0.1",
    "react-dom": "^17.0.1",
    "url-loader": "^4.1.1"
  },
  "browserslist": {
    "production": [
      ">0.5%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  },
  "devDependencies": {
    "docusaurus-lunr-search": "^2.1.15",
    "jsdoc-to-markdown": "^7.1.0",
    "mermaid": "^8.13.4",
    "openapi-comment-parser": "^1.0.0",
    "remark-mermaid": "^0.2.0"
  }
}

My docusaurus.config.js

// @ts-check
// Note: type annotations allow type checking and IDEs autocompletion

const remarkMermaid = require("remark-mermaid");
const lunrSearch = require.resolve("docusaurus-lunr-search");

const lightCodeTheme = require('prism-react-renderer/themes/github');
const darkCodeTheme = require('prism-react-renderer/themes/dracula');

/** @type {import('@docusaurus/types').Config} */
const config = {
  title: 'Docs',
  tagline: 'Enjoy Docs!',
  url: 'https://your-docusaurus-test-site.com',
  baseUrl: '/',
  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',
  favicon: 'img/favicon.ico',
  organizationName: 'Docs', // Usually your GitHub org/user name.
  projectName: 'Docs', // Usually your repo name.

  scripts: [
    "https://cdnjs.cloudflare.com/ajax/libs/mermaid/8.8.4/mermaid.min.js",
    "/init.js"
  ],

  plugins: [
    //[
    //  "docusaurus-plugin-openapi", {
    //    id: "backoffice_rest_api",
    //    routeBasePath: "rest-api-backoffice",
    //    path: "./rest_api_backoffice.json",
    //    proxy: {
    //      "/proxy": {
    //        target: "http://localhost:8090",
    //        pathRewrite: { "^/proxy": "" }
    //      }
    //    }
    //  }
    //],
    ["docusaurus-plugin-openapi", {
       id: "kiosk_rest_api",
       path: "rest-api-kiosk",
       openapiPath: "./rest_api_kiosk.json",
       proxy: {
          "/proxy": {
             target: "http://localhost:8091",
             pathRewrite: { "^/proxy": "" }
          }
       }
    }],
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'js_docs_backoffice',
        path: 'js_docs_backoffice',
        routeBasePath: 'js-docs-backoffice',
        sidebarPath: require.resolve('./sidebars.js'),
      }, 
    ],
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'js_docs_kiosk',
        path: 'js_docs_kiosk',
        routeBasePath: 'js-docs-kiosk',
        sidebarPath: require.resolve('./sidebars.js'),
      }, 
    ],
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'js_docs_student',
        path: 'js_docs_student',
        routeBasePath: 'js-docs-student',
        sidebarPath: require.resolve('./sidebars.js'),
      }, 
    ],
    lunrSearch
  ],

  presets: [
    [
      'docusaurus-preset-openapi',
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        docs: {
          sidebarPath: require.resolve('./sidebars.js'),
          // Please change this to your repo.
          remarkPlugins: [[remarkMermaid, { simple: true }]]
        },
        blog: {
          showReadingTime: true,
          // Please change this to your repo.
        },
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
        api: {
          path: './rest_api_backoffice.json',
          routeBasePath: 'rest-api-backoffice',
        },
      }),
    ],
  ],

  themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    ({
      hideableSidebar: true,
      navbar: {
        hideOnScroll: true,
        title : 'Docs',
        logo: {
          alt : 'Logo',
          src : 'img/logo.svg',
        },
        items: [
          {
            type     : 'doc',
            docId    : 'intro',
            position : 'left',
            label    : 'Tutorial',
          },
          {
            type: 'dropdown',
            label: 'JS Docs',
            position: 'left',
            items: [
              {
                type: 'doc',
                label: 'Backoffice',
                docsPluginId: 'js_docs_backoffice',
                docId: 'intro',
              },
              {
                type: 'doc',
                label: 'Kiosk',
                docsPluginId: 'js_docs_kiosk',
                docId: 'intro',
              },
              {
                type: 'doc',
                label: 'Student',
                docsPluginId: 'js_docs_student',
                docId: 'intro',
              },
            ],
          },
          {
            type: 'dropdown',
            label: 'REST APIs',
            position: 'left',
            items: [
              {
                to: 'rest-api-backoffice',
                label: 'Backoffice',
              },
              {
                to: 'rest-api-kiosk',
                label: 'Kiosk',
              },
              {
                to: 'rest-api-student',
                label: 'Student',
              },
            ],
          },
          {
             to       : '/blog',
             label    : 'Blog',
             position : 'left'
          },
          {
            href     : 'https://gitlab.com',
            label    : 'GitLab',
            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: 'GitLab',
                href: 'https://gitlab.com',
              },
            ],
          },
        ],
        copyright: `Copyright © ${new Date().getFullYear()} Company.`,
      },
      prism: {
        theme: lightCodeTheme,
        darkTheme: darkCodeTheme,
      },
    }),
};

module.exports = config;

Also, Is it possible to use just multiple plugins and skip using the docusaurus-preset-openapi preset?

[bourdakos1]

If you are using both the preset and the plugin, you may need to have both of them installed. However, It shouldn’t be strictly necessary, because installing the preset should also install the plugin and the theme.

It may be helpful to delete node_modules / any lockfile and try to reinstall.

You can also check out the demo folder of this project for a working example of using multiple instances of the plugin.

Also, Is it possible to use just multiple plugins and skip using the docusaurus-preset-openapi preset?

Using the preset is just a convenience and not a requirement. In order to use the plugin without the preset, you will need to install the plugin and the theme. The plugin usage will be exactly the same as shown in your current config, however you will also need to add a themes stanza that includes docusaurus-theme-openapi.

[bourdakos1]

This shouldn't be causing the error you are seeing but I think your plugin config:

["docusaurus-plugin-openapi", {
  id: "kiosk_rest_api",
  path: "rest-api-kiosk",
  openapiPath: "./rest_api_kiosk.json",
  proxy: {
    "/proxy": {
      target: "http://localhost:8091",
      pathRewrite: { "^/proxy": "" }
    }
  }
}],

should look like this:

["docusaurus-plugin-openapi", {
  id: "kiosk_rest_api",
  path: "./rest_api_kiosk.json",
  routeBasePath: "rest-api-kiosk",

  // I'm also not sure what the does?
  proxy: {
    "/proxy": {
      target: "http://localhost:8091",
      pathRewrite: { "^/proxy": "" }
    }
  }
}],

[Anthony-Gaudino]

Thank you @bourdakos1

Changing the plugin definition to:

    ["docusaurus-plugin-openapi", {
       id: "kiosk_rest_api",
       path: "./rest_api_kiosk.json",
       routeBasePath: "rest-api-kiosk",
       //proxy: {
       //   "/proxy": {
       //      target: "http://localhost:8091",
       //      pathRewrite: { "^/proxy": "" }
       //   }
       //}
    }],

Solves the error.

---

Now, this part:

       proxy: {
          "/proxy": {
             target: "http://localhost:8091",
             pathRewrite: { "^/proxy": "" }
          }
       }

I have seen on the video: https://www.youtube.com/watch?v=-Z9Zn8RHf0c&t=15s
This specifies where the server URL and port is. By default it is http://localhost:3000, but I need to change it.

If I put:

    ["docusaurus-plugin-openapi", {
       id: "kiosk_rest_api",
       path: "./rest_api_kiosk.json",
       routeBasePath: "rest-api-kiosk",
       proxy: {
          "/proxy": {
             target: "http://localhost:8091",
             pathRewrite: { "^/proxy": "" }
          }
       }
    }],

I have the error:

A validation error occurred.
The validation system was added recently to Docusaurus as an attempt to avoid user configuration errors.
We may have made some mistakes.
If you think your configuration is valid and should keep working, please open a bug report.

ValidationError: "proxy" is not allowed

This worked on docusaurus-plugin-openapi 1.x

[bourdakos1]

Maybe proxy was from the alpha version of docusaurus? I'll try to see where this option comes from. In the meantime, if you remove proxy does it at least build?

[bourdakos1]

@Anthony-Gaudino It looks like at one point docusaurus would pass devServer configs (which includes proxy) to Webpack, but it looks like they don't support that anymore. I would open an issue on docusaurus if this is a functionality you need.

[Anthony-Gaudino]

Hi @bourdakos1,

Sorry for late reply.

Maybe proxy was from the alpha version of docusaurus? I'll try to see where this option comes from. In the meantime, if you remove proxy does it at least build?

Removing proxy builds it.

---

@Anthony-Gaudino It looks like at one point docusaurus would pass devServer configs (which includes proxy) to Webpack, but it looks like they don't support that anymore. I would open an issue on docusaurus if this is a functionality you need.

I have been using Beta 9 version of Docusaurus always, so I tested this on same version of Docusaurus, beta 9 with the 0.1.1 version of the plugin and the error didn't happen, so it seems that there's something with the plugin itself and not Docusaurus, something was changed on 0.2.0 or other versions that broke it.

By the way, the most recent Docusarus version now is Beta 13 so maybe you want to update it on the plugin dependencies.

[bourdakos1]

I have been using Beta 9 version of Docusaurus always, so I tested this on same version of Docusaurus, beta 9 with the 0.1.1 version of the plugin and the error didn't happen, so it seems that there's something with the plugin itself and not Docusaurus, something was changed on 0.2.0 or other versions that broke it.

0.2.0 adds validation that checks that the options passed are valid. Proxy isn’t a valid option so it throws an error now. In beta 9 plugin 0.1.1, it doesn’t throw an error, but it won’t actually start a proxy.

[Josh-Cena]

@bourdakos1 In recent versions (beta.9, iirc) we have upgraded the dev server to v4. I'm actually not aware that plugins can configure the dev server itself, but we didn't remove any plugin lifecycle.

[bourdakos1]

@Josh-Cena This plugin never explicitly had support for this proxy option, but I do vaguely remembering it magically working at some point (somewhere around alpha.68?). I'm not sure if docusaurus was previously using this option under the covers maybe?

I don't think proxy should be a part of this plugin, but it would be a useful feature to be leveraged by this plugin. I'm not sure if this should be something that is baked into docusaurus or if I should create a new plugin who's sole purpose is handling a dev server proxy?

As a proof-of-concept, I attempted to add the following to the configureWebpack lifecycle method:

devServer: {
  proxy: {
    "/proxy": {
      target: "http://localhost:8091",
      pathRewrite: { "^/proxy": "" },
    },
  },
}

However, this didn't seem to have an effect. It looks like at one point devServer was destructured into the devServerConfig object, but that seems to have been removed in the update to Webpack 5. I'm not super well versed in Webpack though, so I'm not sure if the proxy config actually needs to be a part of devServerConfig or not?

[Josh-Cena]

Oh wow, neither was I aware about config.devServer... In fact I only started contributing at around alpha.73, and only got familiar with Webpack quite recently, so I'd appreciate it if you can send a ticket (either bug report or feature request) so we can keep track of the dev server configuration issue

[slorber]

Should be fixed in facebook/docusaurus#6107 and you will be able to write:

function ProxyPlugin(context) {
  return {
    name: 'proxy-plugin',

    configureWebpack() {
      return {
        devServer: {
          proxy: {
            '/hey': {
              target: 'https://google.com',
              pathRewrite: {'^/hey': ''},
            },
          },
        },
      };
    },
  };
}

However, I don't understand how this proxy option used to work with this plugin.
It's not documented anywhere and I don't find this in the source code either 🤷‍♂️ maybe this plugin used to spread unknown options to Webpack config? 🤔

[bourdakos1]

Awesome, thanks!

However, I don't understand how this proxy option used to work with this plugin.
It's not documented anywhere and I don't find this in the source code either 🤷‍♂️ maybe this plugin used to spread unknown options to Webpack config? 🤔

I'm just as confused as you are haha