From ef6ce4cf6719c09d88f469d5af64b5fae45af9be Mon Sep 17 00:00:00 2001 From: Devon-White Date: Sun, 20 Jul 2025 09:52:54 -0400 Subject: [PATCH 1/2] Add maskCredentials as a pluginOption --- demo/docusaurus.config.ts | 3 + demo/templates/api.mustache | 3 + .../docusaurus-plugin-openapi-docs/README.md | 40 ++++++------ .../src/index.ts | 1 + .../src/openapi/openapi.ts | 8 ++- .../src/options.ts | 1 + .../src/types.ts | 1 + .../theme/ApiExplorer/CodeSnippets/index.tsx | 62 ++++++++++++------- .../src/theme/ApiExplorer/index.tsx | 5 ++ 9 files changed, 80 insertions(+), 44 deletions(-) diff --git a/demo/docusaurus.config.ts b/demo/docusaurus.config.ts index 54621edc9..b4a1baffb 100644 --- a/demo/docusaurus.config.ts +++ b/demo/docusaurus.config.ts @@ -268,6 +268,7 @@ const config: Config = { docsPluginId: "classic", config: { petstore_versioned: { + maskCredentials: false, specPath: "examples/petstore.yaml", outputDir: "docs/petstore_versioned", // No trailing slash sidebarOptions: { @@ -327,10 +328,12 @@ const config: Config = { }, } satisfies OpenApiPlugin.Options, burgers: { + maskCredentials: true, specPath: "examples/food/burgers/openapi.yaml", outputDir: "docs/food/burgers", } satisfies OpenApiPlugin.Options, yogurt: { + maskCredentials: false, specPath: "examples/food/yogurtstore/openapi.yaml", outputDir: "docs/food/yogurtstore", } satisfies OpenApiPlugin.Options, diff --git a/demo/templates/api.mustache b/demo/templates/api.mustache index aa1e66166..3969aa281 100644 --- a/demo/templates/api.mustache +++ b/demo/templates/api.mustache @@ -34,6 +34,9 @@ hide_send_button: true {{#frontMatter.show_extensions}} show_extensions: true {{/frontMatter.show_extensions}} +{{#frontMatter.mask_credentials_disabled}} +mask_credentials: false +{{/frontMatter.mask_credentials_disabled}} --- This is a Custom Api Page Generated by docusaurus-openapi-docs using `api.mustache` template diff --git a/packages/docusaurus-plugin-openapi-docs/README.md b/packages/docusaurus-plugin-openapi-docs/README.md index 73121243d..c09d4eb19 100644 --- a/packages/docusaurus-plugin-openapi-docs/README.md +++ b/packages/docusaurus-plugin-openapi-docs/README.md @@ -127,6 +127,7 @@ import type * as OpenApiPlugin from "docusaurus-plugin-openapi-docs"; petstore: { specPath: "examples/petstore.yaml", outputDir: "docs/petstore", + maskCredentials: false, // Disable credential masking in code snippets sidebarOptions: { groupPathsBy: "tag", }, @@ -155,25 +156,26 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following `config` can be configured with the following options: -| Name | Type | Default | Description | -| -------------------- | --------- | ------- | --------------------------------------------------------------------------------------------------------------------------- | -| `specPath` | `string` | `null` | Designated URL or path to the source of an OpenAPI specification file or directory of multiple OpenAPI specification files. | -| `outputDir` | `string` | `null` | Desired output path for generated MDX and sidebar files. | -| `proxy` | `string` | `null` | _Optional:_ Proxy URL to prepend to base URL when performing API requests from browser. | -| `template` | `string` | `null` | _Optional:_ Customize MDX content with a desired template. | -| `infoTemplate` | `string` | `null` | _Optional:_ Customize MDX content for **info** pages only. | -| `tagTemplate` | `string` | `null` | _Optional:_ Customize MDX content for **tag** pages only. | -| `schemaTemplate` | `string` | `null` | _Optional:_ Customize MDX content for **schema** pages only. | -| `downloadUrl` | `string` | `null` | _Optional:_ Designated URL for downloading OpenAPI specification. (requires `info` section/doc) | -| `hideSendButton` | `boolean` | `null` | _Optional:_ If set to `true`, hides the “Send API Request” button in the API demo panel. | -| `showExtensions` | `boolean` | `null` | _Optional:_ If set to `true`, renders operation‑level vendor‑extensions in descriptions. | -| `sidebarOptions` | `object` | `null` | _Optional:_ Set of options for sidebar configuration. See below for a list of supported options. | -| `version` | `string` | `null` | _Optional:_ Version assigned to a single or micro‑spec API specified in `specPath`. | -| `label` | `string` | `null` | _Optional:_ Version label used when generating the version‑selector dropdown menu. | -| `baseUrl` | `string` | `null` | _Optional:_ Base URL for versioned docs in the version‑selector dropdown. | -| `versions` | `object` | `null` | _Optional:_ Options for versioning configuration. See below for a list of supported options. | -| `markdownGenerators` | `object` | `null` | _Optional:_ Customize MDX content via generator functions. See below for a list of supported options. | -| `showSchemas` | `boolean` | `null` | _Optional:_ If set to `true`, generates standalone schema pages and adds them to the sidebar. | +| Name | Type | Default | Description | +| -------------------- | --------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| `specPath` | `string` | `null` | Designated URL or path to the source of an OpenAPI specification file or directory of multiple OpenAPI specification files. | +| `outputDir` | `string` | `null` | Desired output path for generated MDX and sidebar files. | +| `proxy` | `string` | `null` | _Optional:_ Proxy URL to prepend to base URL when performing API requests from browser. | +| `template` | `string` | `null` | _Optional:_ Customize MDX content with a desired template. | +| `infoTemplate` | `string` | `null` | _Optional:_ Customize MDX content for **info** pages only. | +| `tagTemplate` | `string` | `null` | _Optional:_ Customize MDX content for **tag** pages only. | +| `schemaTemplate` | `string` | `null` | _Optional:_ Customize MDX content for **schema** pages only. | +| `downloadUrl` | `string` | `null` | _Optional:_ Designated URL for downloading OpenAPI specification. (requires `info` section/doc) | +| `hideSendButton` | `boolean` | `null` | _Optional:_ If set to `true`, hides the “Send API Request” button in the API demo panel. | +| `showExtensions` | `boolean` | `null` | _Optional:_ If set to `true`, renders operation‑level vendor‑extensions in descriptions. | +| `maskCredentials` | `boolean` | `true` | _Optional:_ If set to `false`, disables credential masking in generated code snippets. By default, credentials are masked for security. | +| `sidebarOptions` | `object` | `null` | _Optional:_ Set of options for sidebar configuration. See below for a list of supported options. | +| `version` | `string` | `null` | _Optional:_ Version assigned to a single or micro‑spec API specified in `specPath`. | +| `label` | `string` | `null` | _Optional:_ Version label used when generating the version‑selector dropdown menu. | +| `baseUrl` | `string` | `null` | _Optional:_ Base URL for versioned docs in the version‑selector dropdown. | +| `versions` | `object` | `null` | _Optional:_ Options for versioning configuration. See below for a list of supported options. | +| `markdownGenerators` | `object` | `null` | _Optional:_ Customize MDX content via generator functions. See below for a list of supported options. | +| `showSchemas` | `boolean` | `null` | _Optional:_ If set to `true`, generates standalone schema pages and adds them to the sidebar. | ### sidebarOptions diff --git a/packages/docusaurus-plugin-openapi-docs/src/index.ts b/packages/docusaurus-plugin-openapi-docs/src/index.ts index 6c66e7e69..973f1cbab 100644 --- a/packages/docusaurus-plugin-openapi-docs/src/index.ts +++ b/packages/docusaurus-plugin-openapi-docs/src/index.ts @@ -234,6 +234,7 @@ hide_send_button: true {{#frontMatter.show_extensions}} show_extensions: true {{/frontMatter.show_extensions}} +{{#frontMatter.mask_credentials_disabled}}mask_credentials: false{{/frontMatter.mask_credentials_disabled}} --- {{{markdown}}} diff --git a/packages/docusaurus-plugin-openapi-docs/src/openapi/openapi.ts b/packages/docusaurus-plugin-openapi-docs/src/openapi/openapi.ts index 212e7cd7b..486a13751 100644 --- a/packages/docusaurus-plugin-openapi-docs/src/openapi/openapi.ts +++ b/packages/docusaurus-plugin-openapi-docs/src/openapi/openapi.ts @@ -48,7 +48,7 @@ function jsonToCollection(data: OpenApiObject): Promise { if (!schemaPack.validationResult?.result) { return reject(schemaPack.validationResult?.reason); } - + schemaPack.convert((_err: any, conversionResult: any) => { if (_err || !conversionResult.result) { return reject(_err || conversionResult.reason); @@ -256,6 +256,9 @@ function createItems( ...(options?.showExtensions && { show_extensions: options.showExtensions, }), + ...(options?.maskCredentials === false && { + mask_credentials_disabled: true, + }), }, api: { ...defaults, @@ -409,6 +412,9 @@ function createItems( ...(options?.showExtensions && { show_extensions: options.showExtensions, }), + ...(options?.maskCredentials === false && { + mask_credentials_disabled: true, + }), }, api: { ...defaults, diff --git a/packages/docusaurus-plugin-openapi-docs/src/options.ts b/packages/docusaurus-plugin-openapi-docs/src/options.ts index 3c46e27f5..9bad1d90f 100644 --- a/packages/docusaurus-plugin-openapi-docs/src/options.ts +++ b/packages/docusaurus-plugin-openapi-docs/src/options.ts @@ -49,6 +49,7 @@ export const OptionsSchema = Joi.object({ markdownGenerators: markdownGenerators, showSchemas: Joi.boolean(), disableCompression: Joi.boolean(), + maskCredentials: Joi.boolean(), version: Joi.string().when("versions", { is: Joi.exist(), then: Joi.required(), diff --git a/packages/docusaurus-plugin-openapi-docs/src/types.ts b/packages/docusaurus-plugin-openapi-docs/src/types.ts index eec717e5c..4f7310f6d 100644 --- a/packages/docusaurus-plugin-openapi-docs/src/types.ts +++ b/packages/docusaurus-plugin-openapi-docs/src/types.ts @@ -52,6 +52,7 @@ export interface APIOptions { markdownGenerators?: MarkdownGenerator; showSchemas?: boolean; disableCompression?: boolean; + maskCredentials?: boolean; } export interface MarkdownGenerator { diff --git a/packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/CodeSnippets/index.tsx b/packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/CodeSnippets/index.tsx index ff830d8f3..dc0dde0b4 100644 --- a/packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/CodeSnippets/index.tsx +++ b/packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/CodeSnippets/index.tsx @@ -29,6 +29,7 @@ export const languageSet: Language[] = generateLanguageSet(); export interface Props { postman: sdk.Request; codeSamples: CodeSample[]; + maskCredentials?: boolean; } function CodeTab({ children, hidden, className }: any): React.JSX.Element { @@ -39,7 +40,11 @@ function CodeTab({ children, hidden, className }: any): React.JSX.Element { ); } -function CodeSnippets({ postman, codeSamples }: Props) { +function CodeSnippets({ + postman, + codeSamples, + maskCredentials: propMaskCredentials, +}: Props) { const { siteConfig } = useDocusaurusContext(); const contentType = useTypedSelector((state: any) => state.contentType.value); @@ -53,33 +58,42 @@ function CodeSnippets({ postman, codeSamples }: Props) { const headerParams = useTypedSelector((state: any) => state.params.header); const auth = useTypedSelector((state: any) => state.auth); - const clonedAuth = cloneDeep(auth); - let placeholder: string; - function cleanCredentials(obj: any) { - for (const key in obj) { - if (typeof obj[key] === "object" && obj[key] !== null) { - // use name as placeholder if exists - const comboAuthId = Object.keys(obj).join(" and "); - const authOptions = - clonedAuth?.options?.[key] ?? clonedAuth?.options?.[comboAuthId]; - placeholder = authOptions?.[0]?.name; - obj[key] = cleanCredentials(obj[key]); - } else { - obj[key] = `<${placeholder ?? key}>`; - } - } + // Check if credential masking is enabled (default: true) + const maskCredentials = propMaskCredentials ?? true; - return obj; - } + // Clone Auth if maskCredentials is not false + const cleanedAuth = maskCredentials + ? (() => { + const clonedAuth = cloneDeep(auth); + let placeholder: string; + + function cleanCredentials(obj: any) { + for (const key in obj) { + if (typeof obj[key] === "object" && obj[key] !== null) { + // use name as placeholder if exists + const comboAuthId = Object.keys(obj).join(" and "); + const authOptions = + clonedAuth?.options?.[key] ?? + clonedAuth?.options?.[comboAuthId]; + placeholder = authOptions?.[0]?.name; + obj[key] = cleanCredentials(obj[key]); + } else { + obj[key] = `<${placeholder ?? key}>`; + } + } + + return obj; + } - // scrub credentials from code snippets - const cleanedAuth = { - ...clonedAuth, - data: cleanCredentials(clonedAuth.data), - }; + return { + ...clonedAuth, + data: cleanCredentials(clonedAuth.data), + }; + })() + : auth; - // Create a Postman request object using cleanedAuth + // Create a Postman request object using cleanedAuth or original auth const cleanedPostmanRequest = buildPostmanRequest(postman, { queryParams, pathParams, diff --git a/packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/index.tsx b/packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/index.tsx index e04e8b4dd..89a9de01c 100644 --- a/packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/index.tsx +++ b/packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/index.tsx @@ -7,6 +7,7 @@ import React from "react"; +import { useDoc } from "@docusaurus/plugin-content-docs/client"; import CodeSnippets from "@theme/ApiExplorer/CodeSnippets"; import Request from "@theme/ApiExplorer/Request"; import Response from "@theme/ApiExplorer/Response"; @@ -21,6 +22,9 @@ function ApiExplorer({ item: NonNullable; infoPath: string; }) { + const metadata = useDoc(); + const { mask_credentials } = metadata.frontMatter; + const postman = new sdk.Request( item.postman ? sdk.Request.isRequest(item.postman) @@ -36,6 +40,7 @@ function ApiExplorer({ )} From 0da0a2f496e99fc43674b87fec99a9f36c2887c0 Mon Sep 17 00:00:00 2001 From: Devon-White Date: Sun, 20 Jul 2025 10:03:55 -0400 Subject: [PATCH 2/2] fix formatting to be consistent --- packages/docusaurus-plugin-openapi-docs/src/index.ts | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/packages/docusaurus-plugin-openapi-docs/src/index.ts b/packages/docusaurus-plugin-openapi-docs/src/index.ts index 973f1cbab..570fcf2b5 100644 --- a/packages/docusaurus-plugin-openapi-docs/src/index.ts +++ b/packages/docusaurus-plugin-openapi-docs/src/index.ts @@ -234,7 +234,9 @@ hide_send_button: true {{#frontMatter.show_extensions}} show_extensions: true {{/frontMatter.show_extensions}} -{{#frontMatter.mask_credentials_disabled}}mask_credentials: false{{/frontMatter.mask_credentials_disabled}} +{{#frontMatter.mask_credentials_disabled}} +mask_credentials: false +{{/frontMatter.mask_credentials_disabled}} --- {{{markdown}}}