From 54444a395c3fac24bf49ceadde86b475d17a43e0 Mon Sep 17 00:00:00 2001
From: Alvin Bryan <107407814+alvinometric@users.noreply.github.com>
Date: Thu, 14 Nov 2024 11:07:23 +0000
Subject: [PATCH] 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
## 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";
```
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.
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 | 4 ++-
website/clean-generated-docs.mjs | 30 -----------------
website/docusaurus.config.ts | 5 +--
website/package.json | 5 ++-
website/prepare-generated-docs.mjs | 52 ++++++++++++++++++++++++++++++
website/yarn.lock | 20 ++----------
6 files changed, 61 insertions(+), 55 deletions(-)
delete mode 100644 website/clean-generated-docs.mjs
create mode 100644 website/prepare-generated-docs.mjs
diff --git a/website/README.md b/website/README.md
index 12448c4f50..2c25b14b6b 100644
--- a/website/README.md
+++ b/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
diff --git a/website/clean-generated-docs.mjs b/website/clean-generated-docs.mjs
deleted file mode 100644
index b8bfcdd419..0000000000
--- a/website/clean-generated-docs.mjs
+++ /dev/null
@@ -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: ['', '""', '"path":['],
-};
-
-replaceInFileSync(options);
diff --git a/website/docusaurus.config.ts b/website/docusaurus.config.ts
index 1ed84a3389..9146bbdb76 100644
--- a/website/docusaurus.config.ts
+++ b/website/docusaurus.config.ts
@@ -874,10 +874,7 @@ const config: Config = {
docsPluginId: 'classic',
config: {
server: {
- specPath:
- process.env.OPENAPI_SOURCE === 'localhost'
- ? 'http://localhost:4242/docs/openapi.json'
- : 'https://us.app.unleash-hosted.com/ushosted/docs/openapi.json',
+ specPath: 'docs/generated/openapi.json',
outputDir: 'docs/reference/api/unleash',
sidebarOptions: {
groupPathsBy: 'tag',
diff --git a/website/package.json b/website/package.json
index 12ca89971d..69ef66cc48 100644
--- a/website/package.json
+++ b/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",
- "replace-in-file": "^8.2.0"
+ "react-dom": "^18.3.1"
},
"browserslist": {
"production": [
diff --git a/website/prepare-generated-docs.mjs b/website/prepare-generated-docs.mjs
new file mode 100644
index 0000000000..20a46ffc31
--- /dev/null
+++ b/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: '',
+}];
+
+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}`);
+
+
diff --git a/website/yarn.lock b/website/yarn.lock
index 58c490cd05..2e2665f5cf 100644
--- a/website/yarn.lock
+++ b/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: