From 561de64c6f1f2b29acd2c4a507cf9674f2ade033 Mon Sep 17 00:00:00 2001 From: Axel Pettersson Date: Sun, 17 Aug 2025 12:41:17 +0200 Subject: [PATCH 1/3] feat(openapi-metadata): Update Scalar UI integration and add Scalar UI options --- docs/openapi-metadata/examples.md | 4 +- docs/openapi-metadata/ui.md | 2 +- packages/openapi-metadata/src/ui/scalar.ts | 69 ++++++++++++++++++++-- 3 files changed, 67 insertions(+), 8 deletions(-) diff --git a/docs/openapi-metadata/examples.md b/docs/openapi-metadata/examples.md index ac8bc4caa..a676fe5fe 100644 --- a/docs/openapi-metadata/examples.md +++ b/docs/openapi-metadata/examples.md @@ -23,7 +23,7 @@ app.get("/api", async (req, res) => { }); app.get("/api/docs", (req, res) => { - const ui = generateScalarUI("/api"); + const ui = generateScalarUI("/api", { theme: "purple" }); res.send(ui); }); ``` @@ -45,7 +45,7 @@ app.get("/api", async () => { }); app.get("/api/docs", () => { - const ui = generateScalarUI("/api"); + const ui = generateScalarUI("/api", { theme: "purple" }); return ui; }); ``` diff --git a/docs/openapi-metadata/ui.md b/docs/openapi-metadata/ui.md index 104da61a0..8738d3b0f 100644 --- a/docs/openapi-metadata/ui.md +++ b/docs/openapi-metadata/ui.md @@ -11,7 +11,7 @@ title: UI integrations ```ts twoslash import { generateScalarUI } from "openapi-metadata/ui"; -generateScalarUI("http://localhost:3000/api"); +generateScalarUI("http://localhost:3000/api", { theme: "purple" }); ``` ## [Swagger UI](https://swagger.io/tools/swagger-ui/) diff --git a/packages/openapi-metadata/src/ui/scalar.ts b/packages/openapi-metadata/src/ui/scalar.ts index 1d7e9a87c..967429dad 100644 --- a/packages/openapi-metadata/src/ui/scalar.ts +++ b/packages/openapi-metadata/src/ui/scalar.ts @@ -1,9 +1,64 @@ +/** + * Options for generating the Scalar UI. + * + * See: https://guides.scalar.com/scalar/scalar-api-references/configuration + */ +export type GenerateScalarUIOptions = { + url?: string; + content?: string | object | (() => object) | null; + title?: string; + slug?: string; + baseServerURL?: string; + hideClientButton?: boolean; + proxyUrl?: string; + searchHotKey?: string; + servers?: any[]; + showSidebar?: boolean; + theme?: + | 'alternate' + | 'default' + | 'moon' + | 'purple' + | 'solarized' + | 'bluePlanet' + | 'deepSpace' + | 'saturn' + | 'kepler' + | 'elysiajs' + | 'fastify' + | 'mars' + | 'laserwave' + | 'none'; + persistAuth?: boolean; + plugins?: any[]; + layout?: 'modern' | 'classic'; + isLoading?: boolean; + hideModels?: boolean; + documentDownloadType?: 'yaml' | 'json' | 'both' | 'none'; + hideDownloadButton?: boolean; + hideTestRequestButton?: boolean; + hideSearch?: boolean; + darkMode?: boolean; + forceDarkModeState?: 'dark' | 'light'; + hideDarkModeToggle?: boolean; + metaData?: any; + favicon?: string; + hiddenClients?: Record | string[] | true; + defaultHttpClient?: { targetKey: string; clientKey: string }; + customCss?: string; + pathRouting?: { basePath: string }; + withDefaultFonts?: boolean; + defaultOpenAllTags?: boolean; + tagsSorter?: 'alpha' | ((a: any, b: any) => number); + operationsSorter?: 'alpha' | 'method' | ((a: any, b: any) => number); +}; + /** * Generates HTML to display Scalar UI. * * @see https://scalar.com/ */ -export function generateScalarUI(url: string) { +export function generateScalarUI(url: string, options: Omit = {}) { return ` @@ -15,11 +70,15 @@ export function generateScalarUI(url: string) { content="width=device-width, initial-scale=1" /> - +
+ `; From fb57390b825478f07d2e934aaa1fa7dc71277738 Mon Sep 17 00:00:00 2001 From: Axel Pettersson Date: Sun, 17 Aug 2025 12:50:04 +0200 Subject: [PATCH 2/3] Add changeset --- .changeset/short-bears-sneeze.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/short-bears-sneeze.md diff --git a/.changeset/short-bears-sneeze.md b/.changeset/short-bears-sneeze.md new file mode 100644 index 000000000..11f739ede --- /dev/null +++ b/.changeset/short-bears-sneeze.md @@ -0,0 +1,5 @@ +--- +"openapi-metadata": patch +--- + +Add configuration options for Scalar UI generation From 8ba731d777c7acfda46e50dc176fef54f7567507 Mon Sep 17 00:00:00 2001 From: Axel Pettersson Date: Sun, 17 Aug 2025 13:14:55 +0200 Subject: [PATCH 3/3] Format --- packages/openapi-metadata/src/ui/scalar.ts | 42 +++++++++++----------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/packages/openapi-metadata/src/ui/scalar.ts b/packages/openapi-metadata/src/ui/scalar.ts index 967429dad..41008ce15 100644 --- a/packages/openapi-metadata/src/ui/scalar.ts +++ b/packages/openapi-metadata/src/ui/scalar.ts @@ -14,32 +14,32 @@ export type GenerateScalarUIOptions = { searchHotKey?: string; servers?: any[]; showSidebar?: boolean; - theme?: - | 'alternate' - | 'default' - | 'moon' - | 'purple' - | 'solarized' - | 'bluePlanet' - | 'deepSpace' - | 'saturn' - | 'kepler' - | 'elysiajs' - | 'fastify' - | 'mars' - | 'laserwave' - | 'none'; + theme?: + | "alternate" + | "default" + | "moon" + | "purple" + | "solarized" + | "bluePlanet" + | "deepSpace" + | "saturn" + | "kepler" + | "elysiajs" + | "fastify" + | "mars" + | "laserwave" + | "none"; persistAuth?: boolean; plugins?: any[]; - layout?: 'modern' | 'classic'; + layout?: "modern" | "classic"; isLoading?: boolean; hideModels?: boolean; - documentDownloadType?: 'yaml' | 'json' | 'both' | 'none'; + documentDownloadType?: "yaml" | "json" | "both" | "none"; hideDownloadButton?: boolean; hideTestRequestButton?: boolean; hideSearch?: boolean; darkMode?: boolean; - forceDarkModeState?: 'dark' | 'light'; + forceDarkModeState?: "dark" | "light"; hideDarkModeToggle?: boolean; metaData?: any; favicon?: string; @@ -49,8 +49,8 @@ export type GenerateScalarUIOptions = { pathRouting?: { basePath: string }; withDefaultFonts?: boolean; defaultOpenAllTags?: boolean; - tagsSorter?: 'alpha' | ((a: any, b: any) => number); - operationsSorter?: 'alpha' | 'method' | ((a: any, b: any) => number); + tagsSorter?: "alpha" | ((a: any, b: any) => number); + operationsSorter?: "alpha" | "method" | ((a: any, b: any) => number); }; /** @@ -58,7 +58,7 @@ export type GenerateScalarUIOptions = { * * @see https://scalar.com/ */ -export function generateScalarUI(url: string, options: Omit = {}) { +export function generateScalarUI(url: string, options: Omit = {}) { return `