Fixed OpenAPI URL renaming (#8726)

## Problem

Our API docs are generated from a specfile that is hosted in
https://us.app.unleash-hosted.com/ushosted

By default the API docs UI will show that URL, which we don't want


![image](https://github.com/user-attachments/assets/c125cf6c-8c97-4a56-84a8-3989725d2e95)

## Previously

We ran a find-and-replace after the mdx files were generated with
`replace-in-file`

## Now

The previous solution is no longer possible because the openapi plugin
changed. Basically, before it generated markdown files that looked like
this:

```
# Create API Key

https://unleash-hosted/whatever

bla bla bla
```
Now it generates files that do not contain the URL and look like this:

```
import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Configure project access"}
>
</Heading>
```
which themselves get compiled.

## Solution

This PR now downloads the specfile, makes a local copy, then an alters
the server URL in the copy, then uses that local file to generate the
docs.


![image](https://github.com/user-attachments/assets/039644a6-1e72-4145-9c67-9e6203b1673b)


I didn't want to make any changes to the actual spec logic because this
essentially just a plugin quirk

---

[PREVIEW
LINK](https://unleash-docs-git-alvin-fix-openapi-rename-unleash-team.vercel.app/reference/api/unleash/get-addon)

website/README.md

@@ -39,12 +39,14 @@ This command generates static content into the `build` directory and can be serv
 
 ## Cleaning dependencies and caches
 
-If you're upgrading a lot of dependencies, it's always good to delete the `node_modules` directory and clean the various caches.
+If you're upgrading many dependencies, it's always good to delete the `node_modules` directory, refresh `yarn.lock` and clean the various caches.
 
 ```console
 rm -rf node_modules
 rm -rf .docusaurus
 rm -rf docs/reference/api/unleash
+rm -rf yarn.lock
+touch yarn.lock
 ```
 
 ## Troubleshooting

website/clean-generated-docs.mjs

@@ -1,30 +0,0 @@
-// Description:
-//
-// ## What
-//
-// This 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.
-import { replaceInFileSync } from 'replace-in-file';
-
-const options = {
-    files: 'docs/reference/api/**/*.api.mdx',
-    from: [
-        /\/ushosted/g,
-        /"https:\/\/us.app.unleash-hosted.com(\/ushosted)?"/g,
-        '"path":["ushosted",',
-    ],
-    to: ['', '"<your-unleash-url>"', '"path":['],
-};
-
-replaceInFileSync(options);

website/docusaurus.config.ts

@@ -874,10 +874,7 @@ const config: Config = {
                 docsPluginId: 'classic',
                 config: {
                     server: {
-                        specPath:
+                        specPath: 'docs/generated/openapi.json',
-                            process.env.OPENAPI_SOURCE === 'localhost'
-                                ? 'http://localhost:4242/docs/openapi.json'
-                                : 'https://us.app.unleash-hosted.com/ushosted/docs/openapi.json',
                         outputDir: 'docs/reference/api/unleash',
                         sidebarOptions: {
                             groupPathsBy: 'tag',

website/package.json

@@ -11,7 +11,7 @@
     "build": "yarn generate && yarn fetch-remote-content && docusaurus build",
     "swizzle": "docusaurus swizzle",
     "fetch-remote-content": "docusaurus download-remote-content-external && docusaurus download-remote-content-sdks",
-    "generate": "docusaurus gen-api-docs all && node clean-generated-docs.mjs",
+    "generate": "node prepare-generated-docs.mjs && docusaurus gen-api-docs all",
     "deploy": "yarn generate && yarn fetch-remote-content && docusaurus deploy",
     "clear": "docusaurus clear",
     "serve": "docusaurus serve",
@@ -34,8 +34,7 @@
     "prism-react-renderer": "^2.4.0",
     "prism-svelte": "^0.5.0",
     "react": "^18.3.1",
-    "react-dom": "^18.3.1",
+    "react-dom": "^18.3.1"
-    "replace-in-file": "^8.2.0"
   },
   "browserslist": {
     "production": [

website/prepare-generated-docs.mjs

@@ -0,0 +1,52 @@
+// Description:
+//
+// ## What
+//
+// This 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.
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const url = 'https://us.app.unleash-hosted.com/ushosted/docs/openapi.json';
+
+// Fetch the OpenAPI spec
+const response = await fetch(url);
+if (!response.ok) {
+    throw new Error(`Failed to fetch OpenAPI spec: ${response.statusText}`);
+}
+
+const data = await response.json();
+
+data.servers = [{
+    url: '<your-unleash-url>',
+}];
+
+const outputDir = './docs/generated/'
+
+// Write the JSON to file
+const outputPath = path.join(outputDir, 'openapi.json')
+
+// Ensure directory exists
+await fs.mkdir(outputDir, { recursive: true });
+
+await fs.writeFile(
+    outputPath,
+    JSON.stringify(data, null, 2),
+    'utf8'
+);
+
+console.log(`OpenAPI spec saved to ${outputPath}`);
+
+

website/yarn.lock

@@ -4579,7 +4579,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"chalk@npm:^5.0.1, chalk@npm:^5.2.0, chalk@npm:^5.3.0":
+"chalk@npm:^5.0.1, chalk@npm:^5.2.0":
   version: 5.3.0
   resolution: "chalk@npm:5.3.0"
   checksum: 10c0/8297d436b2c0f95801103ff2ef67268d362021b8210daf8ddbe349695333eb3610a71122172ff3b0272f1ef2cf7cc2c41fdaa4715f52e49ffe04c56340feed09
@@ -6893,7 +6893,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"glob@npm:^10.2.2, glob@npm:^10.3.10, glob@npm:^10.3.7, glob@npm:^10.4.2":
+"glob@npm:^10.2.2, glob@npm:^10.3.10, glob@npm:^10.3.7":
   version: 10.4.5
   resolution: "glob@npm:10.4.5"
   dependencies:
@@ -12637,19 +12637,6 @@ plugin-image-zoom@flexanalytics/plugin-image-zoom:
   languageName: node
   linkType: hard
 
-"replace-in-file@npm:^8.2.0":
-  version: 8.2.0
-  resolution: "replace-in-file@npm:8.2.0"
-  dependencies:
-    chalk: "npm:^5.3.0"
-    glob: "npm:^10.4.2"
-    yargs: "npm:^17.7.2"
-  bin:
-    replace-in-file: bin/cli.js
-  checksum: 10c0/a6e4283a774c155c484f222ac11f9dbc21ce64f180b240e95206e05ac856e23205ed0b0b6b0286746b453df0ec3b37a64f93c23b7df9b70cdda8eab57fc6d2d8
-  languageName: node
-  linkType: hard
-
 "require-directory@npm:^2.1.1":
   version: 2.1.1
   resolution: "require-directory@npm:2.1.1"
@@ -14750,7 +14737,6 @@ plugin-image-zoom@flexanalytics/plugin-image-zoom:
     prism-svelte: "npm:^0.5.0"
     react: "npm:^18.3.1"
     react-dom: "npm:^18.3.1"
-    replace-in-file: "npm:^8.2.0"
     typescript: "npm:5.6.3"
   languageName: unknown
   linkType: soft
@@ -14999,7 +14985,7 @@ plugin-image-zoom@flexanalytics/plugin-image-zoom:
   languageName: node
   linkType: hard
 
-"yargs@npm:^17.0.1, yargs@npm:^17.7.2":
+"yargs@npm:^17.0.1":
   version: 17.7.2
   resolution: "yargs@npm:17.7.2"
   dependencies: