Support multi file OpenAPI definitions

[avatarneil]

This package is wonderful, and I've been having a blast working on prototyping serving some of my org's Swagger definitions with it. One thing I've run into, however, is an inability to use file refs as specified in https://redoc.ly/docs/resources/ref-guide/

This is fairly easily reproduced by opening up the example project in this repo, taking one of the schemas in the components section of the openapi.yaml (for example the ApiResponse component), moving it into a new file, and trying to reference it with $ref: './ApiResponse.yaml' (which is what I'd named the file I copied the component to).

I'm currently getting around this by using https://github.com/wework/speccy to merge my JSON Schemas into the same file as my Swagger API spec, however this is reasonably clunky and makes rapid updates locally a pain. I think that adding this functionality would be fantastic, especially for larger APIs, and even the Redocly team encourages breaking specs up into multiple files for readability/composition.

That all being said, I may just be doing something wrong, and this functionality may already exist within redocusaurus! If this is the case, I bet adding an example of this to the example project in this repo would help others who come across the same issue.

[rohit-gohri]

I agree that breaking up specs into multiple files makes for a much better workflow. I think this is possible when generating docs with the redoc cli but not with redocusaurus currently. Even I was using https://github.com/Redocly/openapi-cli to bundle my files into a single yaml.

I think this is a valid use case and would like to add it to the project, but I can't be certain when I would get time.

If you want to give it a try, feel free to do so and open a PR.
We would have to add https://github.com/Redocly/openapi-cli/tree/master/packages/core#bundle here:

redocusaurus/packages/docusaurus-plugin-redoc/src/index.ts

Lines 35 to 38 in 783d464

	if (spec.endsWith('.yaml') || spec.endsWith('.yml')) {
	const parsedSpec = YAML.parse(file);
	content = parsedSpec;
	}

[factoidforrest]

A good bundler is the npm openapi tool itself @openapitools/openapi-generator-cli, which you can invoke from a package.json command like
"schema:copy": "openapi-generator-cli generate -i ../api-spec/schema/yourschema.yaml -g openapi-yaml -o ./static"

Very poorly documented feature, that generator is listed under "documentation generators" 🙄 It cant also output json if you use openapi instead of openapi-yaml and it can take json as well.

Still, its a workaround.

[rohit-gohri]

This will be upcoming in the v1 release. It uses the official redoc openapi-cli under the hood, to maximise compatibility. Also, the bundled yaml will automatically be added as a static asset and used as download url 😄

[rohit-gohri]

Added in the latest beta! It'll be great if you can test it out and give some feedback : #146

Example added here: https://github.com/rohit-gohri/redocusaurus/blob/releases/v1/website/docusaurus.config.js#L19-L24
YAMLs here: https://github.com/rohit-gohri/redocusaurus/tree/releases/v1/website/openapi/multi-yaml

[EdgarRuizUribe]

Hello! First of all I would like to thank you for the great contributions you make to the project. I'm recently using Docusaurus, and your documentation helped me a lot.
But I have some doubts, which I hope you can help me solve.

1. Is there a way to remove the button so that they can download the services file that I refer to from my website?
   

2. Is there a way to group all my remote .yaml files in a side menu, like the one for documents?
   That is to say, that in the upper tabs, there is only one item and when clicking on it, the side menu opens with the different
   documentations. (as the documents section does)

Again, thank you very much for your great contributions on this topic, greetings.

[rohit-gohri]

Hey @EdgarRuizUribe! Happy to help, but best to create a new issue or discussion in the future for questions.

Is there a way to remove the button so that they can download the services file that I refer to from my website?

redoc has an option to hideDownloadButton that you can pass to it by setting it in config:

module.exports = {
  // ...
  presets: [
    [
      'redocusaurus',
      {
        // Plugin Options for loading OpenAPI files
        specs: [
          {
            spec: 'openapi/openapi.yaml',
            route: '/api/',
          },
        ],
        // Theme Options for modifying how redoc renders them
        theme: {
          primaryColor: '#1890ff',
          options: {
            // this is what needs to be set:
            hideDownloadButton: true,
          },
        },
      },
    ],
  ],
  // ...
};

Is there a way to group all my remote .yaml files in a side menu, like the one for documents?

That is currently not supported, there is some discussion with different approaches in this issue : #108 . One way is to use MDX files to render nested sidebars. Best to use that issue for further discussions related to this.