Difficulties with Scalar integration (OpenAPI reference)

[colinmollenhour]

I think it would be a common use-case to want to add OpenAPI docs to one's Docus site (e.g. a great alternative to expensive hosted services like Mintlify, Gitbook, Stoplight, etc.). I tried to setup a fresh Docus site with @scalar/nuxt added, and while it worked, there were a few issues that I wasn't able to find an elegant solution for (read: I gave up for now...). Fixing these is a bit above my skill level, unfortunately.

Problem 1

The header component has a sticky behavior when scrolling on reference pages which conflicts with the sticky behavior of the Scalar sidebar. As you scroll down, the Search widget is hidden behind the Docus header and it just looks bad. In general, both components should be able to coexist without interfering with each other's scrolling/menu behavior on both desktop and mobile.

I tried overriding AppHeader.vue but it doesn't seem to work so it may be necessary to eject entirely from Docus to fix this. My attempt was going to be to just make the Docus header not sticky when on a reference page.

Also in mobile sizes the Scalar header covers the Docus header.. not sure what a good solution is for that.

Problem 2

The color mode is not synced between the Nuxt UI page and the Scalar page. When one is dark and the other is light it looks terrible, of course and they conflict with one another's CSS. It looks fine when they are both the same mode.

I've not tried implementing any solution for this yet, it may be easiest to add some hooks in Scalar to listen for changes in the color mode and apply them accordingly or vice-versa.

Problem 3

It does not work at all in dev mode, I have to build and run the production server to get the Scalar components to appear.

E.g.:

The requested module '/_nuxt/@fs/home/colin/projects/my/nuxt-docs/node_modules/@scalar/openapi-parser/node_modules/ajv-draft-04/dist/index.js?v=521cbf6b' does not provide an export named 'default'

Problem 4

Both Docus and Scalar provide a search feature. If you move the search to the sidebar that fixes having two search button widgets, but there are still two problems:

1. Using the keyboard shortcut opens both search widgets on top of one another
2. One cannot search the "full" site all at once, only the docus content or the scalar content, but not both.

---

As you can see, while it's not completely broken, these are fairly significant issues that give a bad user experience so I've given up on it for now but would love to revisit.

[0PandaDEV]

An openAPI integration would be very useful and is the only thing keeping me from using docus at the moment. I suggest doing something similar to the way fumadocs implements openAPI as a component, which can then be used in the mdx files to render an API page from a spec file.