mirror of
https://github.com/Unleash/unleash.git
synced 2024-12-22 19:07:54 +01:00
54444a395c
## 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"; <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.  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)
53 lines
1.4 KiB
JavaScript
53 lines
1.4 KiB
JavaScript
// 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}`);
|
|
|
|
|