How to specify spec file by relative url

[gugen-otsuki]

Background

I have a web server that returns swagger json (under /api), on the same domain that hosts my docusaurus website.

I have a following config in docusaurus.config.js. It is supposed to fetch swagger spec file from ${BASE_DOMAIN}/api/swagger-doc/v1.

       specs: [
           {
             route: "/api_doc/v1",
             spec: "/api/swagger-doc/v1",
           },
         ],

Problem

I have been using 0.6.0 and I am trying to upgrade to 1.6.0. But after the upgrade I got the following error when I ran docusaurus start. It seems it is trying to find a file on the filesystem but I want it to get resource from the path on the web server. I may be missing something, but is this because the spec field behavior changed after some version? Is there any workaround?Thanks in advance.

 [ERROR] Error: ENOENT: no such file or directory, open '/api/swagger-doc/v1'
[run]     at BaseResolver.<anonymous> (/home/user/my-doc/node_modules/@redocly/openapi-core/lib/resolve.js:119:23)
[run]     at Generator.throw (<anonymous>)
[run]     at rejected (/home/user/my-doc/node_modules/@redocly/openapi-core/lib/resolve.js:6:65)

[rohit-gohri]

but is this because the spec field behavior changed after some version?

Yeah, it changed in v1. We now do build time bundling of api docs to match how docusaurus builds other types of pages (md files). So if you want to use a url it should be an absolute url and be resolvable at build time.

Is there any workaround?

Alternatively, if you want to maintain the old behavior then you can use the package as just a react component in a custom page like here - https://github.com/rohit-gohri/redocusaurus/blob/main/website/src/pages/examples/client-only/index.jsx Relative urls should work here AFAIK.

[rhinodavid]

Seeing this same thing -- my openApiDocument is built in a previous step and exists in the filesystem at build time.

With

 specs: [
                    {
                        spec: `${__dirname}/__build__/openApiDocument.json`,
                        route: '/api/',
                    },
                ],

or

 specs: [
                    {
                        spec: `__build__/openApiDocument.json`,
                        route: '/api/',
                    },
                ],

I get the error:

Loading of api failed for "<redacted file path>/docs-api/openapi.json"
[ERROR] Error: ENOENT: no such file or directory, lstat '<redacted file path>/docs-api/openapi.json'

If i copy the file into openapi.json things work fine. Looks like the configuration isn't being read correctly.

[rhinodavid]

Debug output looks ok

[REDOCUSAURUS] Options: {
  debug: true,
  specs: [
    {
      spec: '<redacted file path>/docs-api/__build__/openApiDocument.json',
      route: '/api/'
    }
  ],
  theme: { primaryColor: '#1890ff' }
}
[REDOCUSAURUS] Specs: [
  {
    spec: '<redacted file path>/docs-api/__build__/openApiDocument.json',
    route: '/api/'
  }
]
[REDOCUSAURUS] Final: {
  "themes": [
    [
      "<redacted file path>/node_modules/docusaurus-theme-redoc/dist/index.js",
      {
        "id": "theme-redoc",
        "primaryColor": "#1890ff"
      }
    ]
  ],
  "plugins": [
    [
      "<redacted file path>/node_modules/docusaurus-plugin-redoc/dist/index.js",
      {
        "spec": "<redacted file path>/docs-api/__build__/openApiDocument.json",
        "route": "/api/",
        "themeId": "theme-redoc",
        "id": "plugin-redoc-0",
        "debug": true
      }
    ]
  ]
}
[REDOCUSAURUS_PLUGIN] Opts Input: {
  config: undefined,
  spec: '<redacted file path>/docs-api/__build__/openApiDocument.json',
  route: '/api/',
  themeId: 'theme-redoc',
  id: 'plugin-redoc-0',
  debug: true,
  layout: {}
}
[REDOCUSAURUS_PLUGIN] Options: {
  layout: {},
  debug: true,
  config: undefined,
  spec: '<redacted file path>/docs-api/__build__/openApiDocument.json',
  route: '/api/',
  themeId: 'theme-redoc',
  id: 'plugin-redoc-0'
}

[rhinodavid]

Ok nevermind -- mine is unrelated. I was switching over from docusaurus-preset-openapi and had left some config lying around

[gugen-otsuki]

Alternatively, if you want to maintain the old behavior then you can use the package as just a react component in a custom page like here

@rohit-gohri Thank you so much. A relative URL in a React component in a custom page worked as expected!