Add a way to display multiple APIs together

[serut]

Hello,

I would like to know if there is a way to display the docusaurus left sidebar.

Currently, using your plugin, I have a full page displaying the swagger doc :

But since I have a lot of microservices, I would like my user be able to access the left sidebar to choose the microservice he wants to view the API.

Overall, I'm looking an integration of redoc with the versionning and the page system of docusaurus.
I've seen that if I create an empty page that has the same URL than what I specified in the docusaurus.config.js file, redocusaurus has an higher priority than the empty page. So if I'm not wrong, I can simulate the versionning of the API using an empty page.

In the screenshot above, the link Processing > API > Overview is the empty page that has the same URL than what is in my conf. It works great so far.

Any help would be appreciated.

[rohit-gohri]

This seems like it would be difficult (or impossible to do). As the API docs are rendered as a single React component. We don't have the content of the sidebar to integrate with the Docusaurus sidebar.

You could create your own React component that wraps the @theme/Redoc component and add custom header navigation elements maybe? I think it will be difficult to merge complex sidebars

[rohit-gohri]

If you want to version your API then just have multiple YAML files, each for each version of your API

[serut]

I have no idea how React component are rendered by docusaurus.
Maybe the page itself should have everything related to redoc so it renders the sidebar then as the main content it renders the redoc in the center of the page. Currently from the docusaurus.config.js file it's pretty impossible to do it
Yes, for versonned API I think the "fake page" is good enough, but I didn't try it

[rohit-gohri]

Maybe the page itself should have everything related to redoc so it renders the sidebar then as the main content it renders the redoc in the center of the page. Currently from the docusaurus.config.js file it's pretty impossible to do it

I don't think that would look good, but I'll keep the issue open if anyone wants to give this a try or to see if there is demand for this.

[serut]

How would you display 10 microservices API, if you don't have a sidebar ?

If there is another way, I'm open to that. :)

[rohit-gohri]

How would you display 10 microservices API, if you don't have a sidebar ?

Sidebar is a good idea, but not a nested sidebar because redoc would have it's own sidebar. Maybe a dropdown would look better, below the header?

[serut]

Either a dropdown or a line bar with all microservice API next to each other

[DatStorm]

Have there been any progress on this? Looking to document 8 different microservices each with their own endpoint.

[rohit-gohri]

How about just adding a dropdown to the navbar (navbar-dropdowns) and grouping all the docs there?

See example I just added :

redocusaurus/website/docusaurus.config.js

Lines 81 to 106 in 62e30bb

	{
	label: 'Examples',
	position: 'left',
	items: [
	{
	label: 'All',
	to: '/examples',
	},
	{
	label: 'Custom Page',
	to: '/examples/custom-page/',
	},
	{
	label: 'Custom Layout',
	to: '/examples/custom-layout/',
	},
	{
	label: 'Using Spec URL',
	to: '/examples/using-spec-url/',
	},
	{
	label: 'Using Spec YAML',
	to: '/examples/using-spec-yaml/',
	},
	],
	},

[DatStorm]

Really nice example I like that. The way I had it working right now was:

1. Create a file with x-tagGroups and then (https://redoc.ly/docs/api-reference-docs/specification-extensions/x-tag-groups/)
2. Merge all files with https://www.npmjs.com/package/openapi-merge

But I like your example solution more. Will do that instead

[serut]

Your solution does not fit on my layout. I have already too much content on the navbar...

Will try to develop something appropriate when I get some spare time. (with versionning, which matters for us)

[serut]

I've created a new React component that I use to display the documentation with double sidebars :

Ok, on small screens it would be hard to use. Maybe I can tweak the theme, when #129 is deployed, to make it more attractive, as the center does not have much space on 22" screens.
As I'm using mdx file to run redoc and not the specs parameter inside docusaurus.config.js file, my API is versionned 🎉 .

[rohit-gohri]

As I'm using mdx file to run redoc and not the specs parameter inside docusaurus.config.js file, my API is versionned 🎉 .

That is genius!! 🎉

Ok, on small screens it would be hard to use.

You can modify the breakpoints in the theme to keep the view always single pane? That sounds like a good compromise

[serut]

That is genius!! 🎉

Thanks !

You can modify the breakpoints in the theme to keep the view always single pane?

Which property are you talking about ?

I'm going to make two more PR : the component that I use to make it possible, as it can be stored on your theme package https://github.com/RegardsOss/RegardsOss.github.io/blob/master/src/redoc/RegardsApiDoc.jsx

And add https://github.com/RegardsOss/RegardsOss.github.io as user of your lib

[rohit-gohri]

You can modify the breakpoints in the theme to keep the view always single pane?

Which property are you talking about ?

https://github.com/Redocly/redoc#redoc-theme-object -> breakpoints

breakpoints # breakpoints for switching three/two and mobile view layouts

small: '50rem'
medium: '85rem'
large: '105rem'

We can force the 2 pane view with this I think (moves examples/code-samples below schema).

And add RegardsOss/RegardsOss.github.io as user of your lib

Would be great!

[serut]

We can force the 2 pane view with this I think (moves examples/code-samples below schema).

It works great ! Thanks

[rohit-gohri]

This is now possible to do with a new ApiDocMdx component in v1.1.0. See the guide here: https://redocusaurus.vercel.app/docs/guides/multiple-apis

And example here: https://redocusaurus.vercel.app/docs/nested/nested-1

[rohit-gohri]

This was done thanks to the ideas from the community! Pretty cool to see all the different usages in the wild.

Thanks to @serut for the initial request and work. And this MDX example with existing components by @TheCatLady here: https://github.com/someengineering/resoto.com/blob/7494b135d87533e54372e2f632f570dab3d06d6d/docs/reference/api.md