Support for external OpenAPI spec

[mathieu-souchet]

Hi all,

Today I tried to upgrade the versions of the NPM modules of my documentation with docusaurus-preset-openapiand i am facing following issue :

❯ npx docusaurus start
[INFO] Starting the development server...
[SUCCESS] Docusaurus website is running at: http://localhost:3000/xxx/documentation/
[ERROR] ValidationError: Invalid configuration object. Webpack has been initialized using a configuration object that does not match the API schema.
 - configuration.module.rules[12] should be one of these:
   ["..." | object { assert?, compiler?, dependency?, descriptionData?, enforce?, exclude?, generator?, include?, issuer?, issuerLayer?, layer?, loader?, mimetype?, oneOf?, options?, parser?, realResource?, resolve?, resource?, resourceFragment?, resourceQuery?, rules?, scheme?, sideEffects?, test?, type?, use? }, ...]
   -> A rule.
   Details:
    * configuration.module.rules[11].include[1]: The provided value "http://my-domain.com/v1/documentation/json/" is not an absolute path!
    * configuration.module.rules[11].include[1]: The provided value "http://my-domain.com/v1/documentation/json/" is not an absolute path!
    * configuration.module.rules[12].exclude[7]: The provided value "http://my-domain.com/v1/documentation/json/" is not an absolute path!
    * configuration.module.rules[12].exclude[7]: The provided value "http://my-domain.com/v1/documentation/json/" is not an absolute path!
    at validate (/Users/xxx/xxx/node_modules/webpack/node_modules/schema-utils/dist/validate.js:105:11)
    at validateSchema (/Users/xxx/xxx/node_modules/webpack/lib/validateSchema.js:78:2)
    at create (/Users/xxx/xxx/node_modules/webpack/lib/webpack.js:111:24)
    at webpack (/Users/xxx/xxx/node_modules/webpack/lib/webpack.js:158:32)
    at f (/Users/xxx/xxx/node_modules/webpack/lib/index.js:64:16)
    at Command.start (/Users/xxx/xxx/node_modules/@docusaurus/core/lib/commands/start.js:124:44)
[INFO] Docusaurus version: 2.2.0
Node version: v18.3.0

My plugin configuration is as following :

  presets: [
    [
      "docusaurus-preset-openapi",
      /** @type {import('docusaurus-preset-openapi').Options} */
      ({
        docs: {
          sidebarPath: require.resolve("./sidebars.js"),
          editUrl: "https://git.xxx.com/xxx/"
        },
        theme: {
          customCss: require.resolve("./src/css/custom.css"),
        },
        api: {
          path: "http://my-domain.com/v1/documentation/json"
        }
      }),
    ],
  ]

It is curious because with following npm depencies versions my doc is running well :

{
  "dependencies": {
    "@docusaurus/core": "^2.0.0",
    "@mdx-js/react": "^1.6.21",
    "clsx": "^1.1.1",
    "docusaurus-preset-openapi": "0.6.1",
    "prism-react-renderer": "^1.2.1",
    "react": "^17.0.1",
    "react-dom": "^17.0.1",
    "url": "^0.11.0"
  }
}

And with following versions it doesn't work :

{
  "dependencies": {
    "@docusaurus/core": "^2.2.0",
    "@mdx-js/react": "^1.6.21",
    "clsx": "^1.1.1",
    "docusaurus-preset-openapi": "0.6.3",
    "prism-react-renderer": "^1.2.1",
    "react": "^17.0.1",
    "react-dom": "^17.0.1",
    "url": "^0.11.0"
  }
}

I'm afraid of an answer like "Sorry but you have to put locally your OpenAPI spec file" because my documentation is in another repository than my API 😅

[mathieu-souchet]

Now I think it might be a problem with trailing slash support (cf. https://github.com/cloud-annotations/docusaurus-openapi/issues/56)

Indeed the remote content is well retrieved with remote url having the slash... 😅

Unfortunately my interface contract is exposed on an url without the last slash 🤷‍♂️

[mathieu-souchet]

Now I think it might be a problem with trailing slash support (cf. https://github.com/cloud-annotations/docusaurus-openapi/issues/56)

in fact it does not change anything with accessible ressource with the trailing slash 😣 :

❯ npm run build

> [email protected] build
> docusaurus build

[INFO] [en] Creating an optimized production build...
[ERROR] Unable to build website for locale en.
[ERROR] ValidationError: Invalid configuration object. Webpack has been initialized using a configuration object that does not match the API schema.
 - configuration[0].module.rules[12] should be one of these:
   ["..." | object { assert?, compiler?, dependency?, descriptionData?, enforce?, exclude?, generator?, include?, issuer?, issuerLayer?, layer?, loader?, mimetype?, oneOf?, options?, parser?, realResource?, resolve?, resource?, resourceFragment?, resourceQuery?, rules?, scheme?, sideEffects?, test?, type?, use? }, ...]
   -> A rule.
   Details:
    * configuration[0].module.rules[11].include[1]: The provided value "http://localhost:3000/v1/documentation/json/" is not an absolute path!

[PavelPikat]

Hi, I am facing the same issue as well :( It's not really convenient to rebuild docs site every time the external API changes. Can this be supported eventually?

[bourdakos1]

I believe this issue is related to a bug with trailing slashes in external spec URLs?

We support fetching an external spec at build time, but we have no plans on supporting any kind of on-the-fly rendering like client or server side rendering.

This project was built to fill the void of static OpenAPI documentation generation. There are a handful of other projects that support what you are looking for, I suggest checking out redocusaurus: https://github.com/rohit-gohri/redocusaurus/

[PavelPikat]

The problem with Redoxusaurus is that it doesnt have 'Try it' feature that this project has 😀

[mathieu-souchet]

I can confirm that the issue is at build time, when based on an url instead of a local directory path.

I have tested with or without the trailing slash, result is the same ...

[korhaliv]

Can also confirm what @mathieu-souchet has reported. Failing during build time when using remote json swagger spec with/without trailing slashes. Using 0.6.3 version

[ERROR] Unable to build website for locale en.
[ERROR] ValidationError: Invalid configuration object. 
Webpack has been initialized using a configuration object that does not match the API schema.
 - configuration[0].module.rules[13] should be one of these:
   ["..." | object { assert?, compiler?, dependency?, descriptionData?, enforce?, exclude?, generator?,
 include?, issuer?, issuerLayer?, layer?, loader?, mimetype?, oneOf?, options?, parser?, realResource?,
 resolve?, resource?, resourceFragment?, resourceQuery?, rules?, scheme?, sideEffects?, test?, type?, use? }, ...]

[Jazz405]

I was able to get debug this and get it working locally, I ended up walking through the @docusaurus/core/lib/commands/start.js file and just removed my url string from the rules. Obviously not a viable solution, but I believe this error's being caused because we're passing the url in the config through to the rules and its rightfully expecting it to be a file.

I think the logic behind passing the contentPath in configureWebpack might be the culprit here

[hughlv]

Any workaround for this issue?

[Kienan6]

+1 this

[LudoDan]

+1

[FloGeez]

+1