## What
This PR updates the version of the docusaurus-openapi plugin we depend
on for openapi docs generation from canary version 0.0.0-514 to stable
release 1.4.4.
Also removes the manual file cleanup that was created as a workaround to
solve the issues we were having.
## Why
When we set the canary version before the weekend it was because it
contained a fix of some of the issues we were having with our docs.
That issue (and the one about file cleanup) have now been released in
v1.4.4, so we can upgrade to a stable version and remove now-redundant
cleanup code.
## Issue
So, we've got an issue with our docs build not working. When building
for production, we get an error that looks a little bit like this:
```
$ docusaurus build
[INFO] [en] Creating an optimized production build...
✔ Client
✖ Server
Compiled with some errors in 40.85s
TypeError: source_default(...).bold is not a function
TypeError: source_default(...).bold is not a function
[ERROR] Unable to build website for locale en.
[ERROR] Error: Failed to compile with errors.
at /Users/thomas/projects/work/unleash/website/node_modules/@docusaurus/core/lib/webpack/utils.js:180:24
at /Users/thomas/projects/work/unleash/website/node_modules/webpack/lib/MultiCompiler.js:554:14
at processQueueWorker (/Users/thomas/projects/work/unleash/website/node_modules/webpack/lib/MultiCompiler.js:491:6)
at processTicksAndRejections (node:internal/process/task_queues:78:11)
[INFO] Docusaurus version: 2.2.0
Node version: v16.14.0
error Command failed with exit code 1.
```
Which isn't very helpful at all. If you go into
`/node_modules/@docusaurus/core/lib/client/serverEntry.js` and modify
the `render` function to log the actual error and remove anything
chalk-related, you get this instead:
```
$ docusaurus build
[INFO] [en] Creating an optimized production build...
✔ Client
✖ Server
Compiled with some errors in 44.62s
Actual error: Error: Unexpected: cant find current sidebar in context
at useCurrentSidebarCategory (main:11618:247)
at MDXContent (main:38139:1593)
at Fb (main:149154:44)
at Ib (main:149156:254)
at W (main:149162:89)
at Jb (main:149165:98)
at Ib (main:149157:145)
at W (main:149162:89)
at Jb (main:149165:98)
at Ib (main:149157:145)
Actual error: Error: Unexpected: cant find current sidebar in context
at useCurrentSidebarCategory (main:11618:247)
at MDXContent (main:38513:1469)
at Fb (main:149154:44)
at Ib (main:149156:254)
at W (main:149162:89)
at Jb (main:149165:98)
at Ib (main:149157:145)
at W (main:149162:89)
at Jb (main:149165:98)
at Ib (main:149157:145)
Error: Unexpected: cant find current sidebar in context
Error: Unexpected: cant find current sidebar in context
[ERROR] Unable to build website for locale en.
[ERROR] Error: Failed to compile with errors.
at /Users/thomas/projects/work/unleash/website/node_modules/@docusaurus/core/lib/webpack/utils.js:180:24
at /Users/thomas/projects/work/unleash/website/node_modules/webpack/lib/MultiCompiler.js:554:14
at processQueueWorker (/Users/thomas/projects/work/unleash/website/node_modules/webpack/lib/MultiCompiler.js:491:6)
at processTicksAndRejections (node:internal/process/task_queues:78:11)
[INFO] Docusaurus version: 2.2.0
Node version: v16.14.0
error Command failed with exit code 1.
```
That's better, but it's still not very clear.
## Getting more info
We've had problems with a similar error message before. Last time it was
caused by an empty file that docusaurus couldn't process.
A similar issue has also been described in [ this docusaurus GitHub
issue ](https://github.com/facebook/docusaurus/issues/7686). That's also
what gave me the idea of changing the logging in the dependency.
I'm currently unsure whether this is caused by the openapi docs or
something else. I've been in touch with the [openapi plugin
maintainer](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/issues/323)
and he has been able to see the same error when building for prod
locally, but it was due to some old generated files.
Worth noting: this only seems to affect the prod build. Building for dev
(`yarn docusaurus start`) works just fine. It also fails locally **and**
in CI, so it _is_ an issue.
## Updating the logging
To get better logging, you can go into the
`/node_modules/@docusaurus/core/lib/client/serverEntry.js` file and
update the `render` function from
```js
export default async function render(locals) {
try {
return await doRender(locals);
}
catch (err) {
// We are not using logger in this file, because it seems to fail with some
// compilers / some polyfill methods. This is very likely a bug, but in the
// long term, when we output native ES modules in SSR, the bug will be gone.
// prettier-ignore
console.error(chalk.red(`${chalk.bold('[ERROR]')} Docusaurus server-side rendering could not render static page with path ${chalk.cyan.underline(locals.path)}.`));
const isNotDefinedErrorRegex = /(?:window|document|localStorage|navigator|alert|location|buffer|self) is not defined/i;
if (isNotDefinedErrorRegex.test(err.message)) {
// prettier-ignore
console.info(`${chalk.cyan.bold('[INFO]')} It looks like you are using code that should run on the client-side only.
To get around it, try using ${chalk.cyan('`<BrowserOnly>`')} (${chalk.cyan.underline('https://docusaurus.io/docs/docusaurus-core/#browseronly')}) or ${chalk.cyan('`ExecutionEnvironment`')} (${chalk.cyan.underline('https://docusaurus.io/docs/docusaurus-core/#executionenvironment')}).
It might also require to wrap your client code in ${chalk.cyan('`useEffect`')} hook and/or import a third-party library dynamically (if any).`);
}
throw err;
}
}
```
to
```js
export default async function render(locals) {
try {
return await doRender(locals);
}
catch (err) {
console.error(err)
throw err;
}
}
```
That'll yield the errors about the current sidebar in context.
## Root cause
Found the issue! 🙋🏼 It's explained in [this comment on the openapi docs
integration](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/issues/323#issuecomment-1311549864)
for now, but in short: we have tags defined that we don't use. They're
being picked up by docusaurus, but don't have the proper context. That's
causing this.
The previously mentioned comment is included here for easy finding in
the future:
### Root cause explanation
The OpenAPI spec we use to generate the docs has a number of tags listed
at the root level. This is necessary for this plugin to pick up tag
categories and is, as far as I can tell, also how it _should_ be done.
However, not all of those tags are in use. Specifically, there's 2 tags
that are not.
When the plugin generates docs from the spec, it generates pages for all
endpoints and all tags and groups them by tag. However, it seems likely
that if a tag doesn't have any associated endpoints, then it won't get
added to the sidebar because there's no endpoint that references it.
But the doc files for these tags do end up lying around in the directory
regardless, and when docusaurus tries to pick up the files in the
generated directory, it also tries to pick up the unused tag files. But
because they're not part of a sidebar, they end up throwing errors
because they can't find the sidebar context.
### How I found it
The fact that I got more instances of the error message without the
sidebar ref than with it made me pay more attention to the number of
errors. I decided to check how many files were in the generated
directory and how many files were referenced from the generated sidebar.
Turns out the difference there was **2**: there were two generated files
in the directory that the sidebar didn't reference.
At this point, it was easy enough to try and delete those files before
rebuilding, and wouldn't you know: it worked!
### Our use case
Now, why do we have tags that are unused in the root spec? Can't we just
remove them?
That's a good question with a bit of a complicated answer. Unleash uses
an open core model and the OpenAPI integration is part of that open
core. The closed-source parts of Unleash are located in another repo and
extend the open-source distribution.
Because the OpenAPI spec is configured in the open-source part,
enterprise-only tags etc also need to be configured there. Then, when
the changes are absorbed into enterprise, we can use the tags there.
It gets more complicated because we use an enterprise instance to
generate the docs (because we want enterprise-endpoints to be listed
too). The instance uses the latest released instance of Unleash to have
the docs most accurately reflect the current state of things.
So, in this case, the tags have been added, but not yet used by any
endpoints, which suddenly causes this build failure. We can add the tags
to the enterprise-version, but the spec wouldn't be updated before the
next release regardless, which will probably be in a week or so.
This isn't an ideal setup, but .. it is what it is.
## Solutions and workarounds
As mentioned in the previous section, the reason the build was failing
was that there were unused tag files that docusaurus tried to include in
the build. Because they don't belong to a sidebar, the compilation
failed.
I've reported the issue to the openapi plugin maintainers and am waiting
for a response.
However, it seems that having unused root tags declared is invalid
according to the spec, so it's something we should look into fixing in
the future.
### Current workaround: cleaning script
The current workaround is to extend the api cleaning script to manually
remove the unused tag files.
### Ideal solution: filter root-level tags
Ideally, we shouldn't list unused OpenAPI tags on the root level at all.
However, because of the way we add root-level tags (as a predefined,
static lists, refer to `src/lib/openapi/index.ts`) and endpoints
(dynamically added at runtime) today, we don't really have a clear way
to filter the list of tags. This gets even more complicated when taking
the enterprise functionality and the potential extra tags they must
have.
This is, however, something that should definitely be looked into.
Working with OpenAPI across multipile repos is already troublesome, so
this is just yet another thing to look into.
Bumps [loader-utils](https://github.com/webpack/loader-utils) from 1.4.0
to 1.4.1.
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a
href="https://github.com/webpack/loader-utils/releases">loader-utils's
releases</a>.</em></p>
<blockquote>
<h2>v1.4.1</h2>
<h3><a
href="https://github.com/webpack/loader-utils/compare/v1.4.0...v1.4.1">1.4.1</a>
(2022-11-07)</h3>
<h3>Bug Fixes</h3>
<ul>
<li>security problem (<a
href="https://github-redirect.dependabot.com/webpack/loader-utils/issues/220">#220</a>)
(<a
href="4504e34c47">4504e34</a>)</li>
</ul>
</blockquote>
</details>
<details>
<summary>Changelog</summary>
<p><em>Sourced from <a
href="https://github.com/webpack/loader-utils/blob/v1.4.1/CHANGELOG.md">loader-utils's
changelog</a>.</em></p>
<blockquote>
<h3><a
href="https://github.com/webpack/loader-utils/compare/v1.4.0...v1.4.1">1.4.1</a>
(2022-11-07)</h3>
<h3>Bug Fixes</h3>
<ul>
<li>security problem (<a
href="https://github-redirect.dependabot.com/webpack/loader-utils/issues/220">#220</a>)
(<a
href="4504e34c47">4504e34</a>)</li>
</ul>
<p><!-- raw HTML omitted --><!-- raw HTML omitted --></p>
</blockquote>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="8f082b39f6"><code>8f082b3</code></a>
chore(release): 1.4.1</li>
<li><a
href="4504e34c47"><code>4504e34</code></a>
fix: security problem (<a
href="https://github-redirect.dependabot.com/webpack/loader-utils/issues/220">#220</a>)</li>
<li>See full diff in <a
href="https://github.com/webpack/loader-utils/compare/v1.4.0...v1.4.1">compare
view</a></li>
</ul>
</details>
<br />
[](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores)
Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.
[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)
---
<details>
<summary>Dependabot commands and options</summary>
<br />
You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot merge` will merge this PR after your CI passes on it
- `@dependabot squash and merge` will squash and merge this PR after
your CI passes on it
- `@dependabot cancel merge` will cancel a previously requested merge
and block automerging
- `@dependabot reopen` will reopen this PR if it is closed
- `@dependabot close` will close this PR and stop Dependabot recreating
it. You can achieve the same result by closing it manually
- `@dependabot ignore this major version` will close this PR and stop
Dependabot creating any more for this major version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this minor version` will close this PR and stop
Dependabot creating any more for this minor version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this dependency` will close this PR and stop
Dependabot creating any more for this dependency (unless you reopen the
PR or upgrade to it yourself)
- `@dependabot use these labels` will set the current labels as the
default for future PRs for this repo and language
- `@dependabot use these reviewers` will set the current reviewers as
the default for future PRs for this repo and language
- `@dependabot use these assignees` will set the current assignees as
the default for future PRs for this repo and language
- `@dependabot use this milestone` will set the current milestone as the
default for future PRs for this repo and language
You can disable automated security fix PRs for this repo from the
[Security Alerts
page](https://github.com/Unleash/unleash/network/alerts).
</details>
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
* #1391: add generated doc cleaning script
## What
The cleaning script replaces all references to the Unleash ushosted instance in the
generated OpenAPI docs. It removes extra path segments (such as leading
`/ushosted` instances) and replaces the ushosted base url with something
user-agnostic.
## Why
When we host the OpenAPI docs in our official documentation, the generated
docs shouldn't necessarily point at _one specific instance_, and especially
not one that the reader is unlikely to ever use. Instead, we can remove all
the bits that are specific to the generation source we use, and make the docs
easier to use. In particular, removing the leading `/ushosted` is likely to
save us loooots of questions.
* #1391: change env var used for generating openapi from localhost
Using NODE_ENV=development doesn't necessarily make sense, so adding
an extra variable sounds reasonable to me.
* #1391: ensure that all generation commands also clean docs
* #1391: change <your-unleash-instance-url> to <your-unleash-url>
* #1391: fix ushosted replacement: not all paths start with /api
* #1391: chore: remove potential `ushosted` ending of api url
In the event that we change the base URL of OpenAPI, so that paths
don't start with `/ushosted/`, the script should still work, changing
those paths into <your-unleash-url> too.
Additionally, remove all instances of `/ushosted` that we find. In the
event that some things switch around or whatever.
* Docs: start experimenting with OpenAPI and docusaurus
* Docs: add docusaurus-theme-openapi-docs pkg
* Wip: current status
* Docs: Add 'docusaurus-plugin-api-docs'
* Move openapi into own sidebar; generate from localhost
* Chore: Update docusaurus plugin for OpenAPI
* Add website/yarn.lock to git
* Fix: fix CSS warning by using flex-end instead of end
* docs: make openapi generated code work again
* docs: make tags work properly with openapi sidebar
* Docs/chore: update OpenAPI tag scheme.
Add a whole bunch of new tags to make it easier to understand
available tags in OpenAPI.
* docs: point to new openapi docs from old api docs
* docs: typo
* Docs: link restructure
* docs: add operation indicators to openapi docs
* docs: change badge color for operations
* docs: update openapi-docs package
It now sorts tags the same as the schema
* docs: pluralize APIs in slug
* docs: update links to generated api docs
* docs: update openapi snapshot tests with new tags
* docs: conditionally load spec from localhost or from file
* docs: Remove changes relating to immediate switchover
* refactor: rename types; extract into separate file
* docs: fix api doc links
