Skip to content

Commit afa156a

Browse files
Devon-WhiteDevon-White
authored
Add maskCredentials as a pluginOption (#1212)
* Add maskCredentials as a pluginOption * fix formatting to be consistent
1 parent 4bab9dd commit afa156a

File tree

9 files changed

+82
-44
lines changed

9 files changed

+82
-44
lines changed

‎demo/docusaurus.config.ts

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -268,6 +268,7 @@ const config: Config = {
268268
docsPluginId: "classic",
269269
config: {
270270
petstore_versioned: {
271+
maskCredentials: false,
271272
specPath: "examples/petstore.yaml",
272273
outputDir: "docs/petstore_versioned", // No trailing slash
273274
sidebarOptions: {
@@ -327,10 +328,12 @@ const config: Config = {
327328
},
328329
} satisfies OpenApiPlugin.Options,
329330
burgers: {
331+
maskCredentials: true,
330332
specPath: "examples/food/burgers/openapi.yaml",
331333
outputDir: "docs/food/burgers",
332334
} satisfies OpenApiPlugin.Options,
333335
yogurt: {
336+
maskCredentials: false,
334337
specPath: "examples/food/yogurtstore/openapi.yaml",
335338
outputDir: "docs/food/yogurtstore",
336339
} satisfies OpenApiPlugin.Options,

‎demo/templates/api.mustache

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,9 @@ hide_send_button: true
3434
{{#frontMatter.show_extensions}}
3535
show_extensions: true
3636
{{/frontMatter.show_extensions}}
37+
{{#frontMatter.mask_credentials_disabled}}
38+
mask_credentials: false
39+
{{/frontMatter.mask_credentials_disabled}}
3740
---
3841

3942
This is a Custom Api Page Generated by docusaurus-openapi-docs using `api.mustache` template

‎packages/docusaurus-plugin-openapi-docs/README.md

Lines changed: 21 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -127,6 +127,7 @@ import type * as OpenApiPlugin from "docusaurus-plugin-openapi-docs";
127127
petstore: {
128128
specPath: "examples/petstore.yaml",
129129
outputDir: "docs/petstore",
130+
maskCredentials: false, // Disable credential masking in code snippets
130131
sidebarOptions: {
131132
groupPathsBy: "tag",
132133
},
@@ -155,25 +156,26 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
155156

156157
`config` can be configured with the following options:
157158

158-
| Name | Type | Default | Description |
159-
| -------------------- | --------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
160-
| `specPath` | `string` | `null` | Designated URL or path to the source of an OpenAPI specification file or directory of multiple OpenAPI specification files. |
161-
| `outputDir` | `string` | `null` | Desired output path for generated MDX and sidebar files. |
162-
| `proxy` | `string` | `null` | _Optional:_ Proxy URL to prepend to base URL when performing API requests from browser. |
163-
| `template` | `string` | `null` | _Optional:_ Customize MDX content with a desired template. |
164-
| `infoTemplate` | `string` | `null` | _Optional:_ Customize MDX content for **info** pages only. |
165-
| `tagTemplate` | `string` | `null` | _Optional:_ Customize MDX content for **tag** pages only. |
166-
| `schemaTemplate` | `string` | `null` | _Optional:_ Customize MDX content for **schema** pages only. |
167-
| `downloadUrl` | `string` | `null` | _Optional:_ Designated URL for downloading OpenAPI specification. (requires `info` section/doc) |
168-
| `hideSendButton` | `boolean` | `null` | _Optional:_ If set to `true`, hides the “Send API Request” button in the API demo panel. |
169-
| `showExtensions` | `boolean` | `null` | _Optional:_ If set to `true`, renders operation‑level vendor‑extensions in descriptions. |
170-
| `sidebarOptions` | `object` | `null` | _Optional:_ Set of options for sidebar configuration. See below for a list of supported options. |
171-
| `version` | `string` | `null` | _Optional:_ Version assigned to a single or micro‑spec API specified in `specPath`. |
172-
| `label` | `string` | `null` | _Optional:_ Version label used when generating the version‑selector dropdown menu. |
173-
| `baseUrl` | `string` | `null` | _Optional:_ Base URL for versioned docs in the version‑selector dropdown. |
174-
| `versions` | `object` | `null` | _Optional:_ Options for versioning configuration. See below for a list of supported options. |
175-
| `markdownGenerators` | `object` | `null` | _Optional:_ Customize MDX content via generator functions. See below for a list of supported options. |
176-
| `showSchemas` | `boolean` | `null` | _Optional:_ If set to `true`, generates standalone schema pages and adds them to the sidebar. |
159+
| Name | Type | Default | Description |
160+
| -------------------- | --------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------- |
161+
| `specPath` | `string` | `null` | Designated URL or path to the source of an OpenAPI specification file or directory of multiple OpenAPI specification files. |
162+
| `outputDir` | `string` | `null` | Desired output path for generated MDX and sidebar files. |
163+
| `proxy` | `string` | `null` | _Optional:_ Proxy URL to prepend to base URL when performing API requests from browser. |
164+
| `template` | `string` | `null` | _Optional:_ Customize MDX content with a desired template. |
165+
| `infoTemplate` | `string` | `null` | _Optional:_ Customize MDX content for **info** pages only. |
166+
| `tagTemplate` | `string` | `null` | _Optional:_ Customize MDX content for **tag** pages only. |
167+
| `schemaTemplate` | `string` | `null` | _Optional:_ Customize MDX content for **schema** pages only. |
168+
| `downloadUrl` | `string` | `null` | _Optional:_ Designated URL for downloading OpenAPI specification. (requires `info` section/doc) |
169+
| `hideSendButton` | `boolean` | `null` | _Optional:_ If set to `true`, hides the “Send API Request” button in the API demo panel. |
170+
| `showExtensions` | `boolean` | `null` | _Optional:_ If set to `true`, renders operation‑level vendor‑extensions in descriptions. |
171+
| `maskCredentials` | `boolean` | `true` | _Optional:_ If set to `false`, disables credential masking in generated code snippets. By default, credentials are masked for security. |
172+
| `sidebarOptions` | `object` | `null` | _Optional:_ Set of options for sidebar configuration. See below for a list of supported options. |
173+
| `version` | `string` | `null` | _Optional:_ Version assigned to a single or micro‑spec API specified in `specPath`. |
174+
| `label` | `string` | `null` | _Optional:_ Version label used when generating the version‑selector dropdown menu. |
175+
| `baseUrl` | `string` | `null` | _Optional:_ Base URL for versioned docs in the version‑selector dropdown. |
176+
| `versions` | `object` | `null` | _Optional:_ Options for versioning configuration. See below for a list of supported options. |
177+
| `markdownGenerators` | `object` | `null` | _Optional:_ Customize MDX content via generator functions. See below for a list of supported options. |
178+
| `showSchemas` | `boolean` | `null` | _Optional:_ If set to `true`, generates standalone schema pages and adds them to the sidebar. |
177179

178180
### sidebarOptions
179181

‎packages/docusaurus-plugin-openapi-docs/src/index.ts

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -234,6 +234,9 @@ hide_send_button: true
234234
{{#frontMatter.show_extensions}}
235235
show_extensions: true
236236
{{/frontMatter.show_extensions}}
237+
{{#frontMatter.mask_credentials_disabled}}
238+
mask_credentials: false
239+
{{/frontMatter.mask_credentials_disabled}}
237240
---
238241
239242
{{{markdown}}}

‎packages/docusaurus-plugin-openapi-docs/src/openapi/openapi.ts

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ function jsonToCollection(data: OpenApiObject): Promise<Collection> {
4848
if (!schemaPack.validationResult?.result) {
4949
return reject(schemaPack.validationResult?.reason);
5050
}
51-
51+
5252
schemaPack.convert((_err: any, conversionResult: any) => {
5353
if (_err || !conversionResult.result) {
5454
return reject(_err || conversionResult.reason);
@@ -256,6 +256,9 @@ function createItems(
256256
...(options?.showExtensions && {
257257
show_extensions: options.showExtensions,
258258
}),
259+
...(options?.maskCredentials === false && {
260+
mask_credentials_disabled: true,
261+
}),
259262
},
260263
api: {
261264
...defaults,
@@ -409,6 +412,9 @@ function createItems(
409412
...(options?.showExtensions && {
410413
show_extensions: options.showExtensions,
411414
}),
415+
...(options?.maskCredentials === false && {
416+
mask_credentials_disabled: true,
417+
}),
412418
},
413419
api: {
414420
...defaults,

‎packages/docusaurus-plugin-openapi-docs/src/options.ts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,7 @@ export const OptionsSchema = Joi.object({
4949
markdownGenerators: markdownGenerators,
5050
showSchemas: Joi.boolean(),
5151
disableCompression: Joi.boolean(),
52+
maskCredentials: Joi.boolean(),
5253
version: Joi.string().when("versions", {
5354
is: Joi.exist(),
5455
then: Joi.required(),

‎packages/docusaurus-plugin-openapi-docs/src/types.ts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,7 @@ export interface APIOptions {
5252
markdownGenerators?: MarkdownGenerator;
5353
showSchemas?: boolean;
5454
disableCompression?: boolean;
55+
maskCredentials?: boolean;
5556
}
5657

5758
export interface MarkdownGenerator {

‎packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/CodeSnippets/index.tsx

Lines changed: 38 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ export const languageSet: Language[] = generateLanguageSet();
2929
export interface Props {
3030
postman: sdk.Request;
3131
codeSamples: CodeSample[];
32+
maskCredentials?: boolean;
3233
}
3334

3435
function CodeTab({ children, hidden, className }: any): React.JSX.Element {
@@ -39,7 +40,11 @@ function CodeTab({ children, hidden, className }: any): React.JSX.Element {
3940
);
4041
}
4142

42-
function CodeSnippets({ postman, codeSamples }: Props) {
43+
function CodeSnippets({
44+
postman,
45+
codeSamples,
46+
maskCredentials: propMaskCredentials,
47+
}: Props) {
4348
const { siteConfig } = useDocusaurusContext();
4449

4550
const contentType = useTypedSelector((state: any) => state.contentType.value);
@@ -53,33 +58,42 @@ function CodeSnippets({ postman, codeSamples }: Props) {
5358
const headerParams = useTypedSelector((state: any) => state.params.header);
5459

5560
const auth = useTypedSelector((state: any) => state.auth);
56-
const clonedAuth = cloneDeep(auth);
57-
let placeholder: string;
5861

59-
function cleanCredentials(obj: any) {
60-
for (const key in obj) {
61-
if (typeof obj[key] === "object" && obj[key] !== null) {
62-
// use name as placeholder if exists
63-
const comboAuthId = Object.keys(obj).join(" and ");
64-
const authOptions =
65-
clonedAuth?.options?.[key] ?? clonedAuth?.options?.[comboAuthId];
66-
placeholder = authOptions?.[0]?.name;
67-
obj[key] = cleanCredentials(obj[key]);
68-
} else {
69-
obj[key] = `<${placeholder ?? key}>`;
70-
}
71-
}
62+
// Check if credential masking is enabled (default: true)
63+
const maskCredentials = propMaskCredentials ?? true;
7264

73-
return obj;
74-
}
65+
// Clone Auth if maskCredentials is not false
66+
const cleanedAuth = maskCredentials
67+
? (() => {
68+
const clonedAuth = cloneDeep(auth);
69+
let placeholder: string;
70+
71+
function cleanCredentials(obj: any) {
72+
for (const key in obj) {
73+
if (typeof obj[key] === "object" && obj[key] !== null) {
74+
// use name as placeholder if exists
75+
const comboAuthId = Object.keys(obj).join(" and ");
76+
const authOptions =
77+
clonedAuth?.options?.[key] ??
78+
clonedAuth?.options?.[comboAuthId];
79+
placeholder = authOptions?.[0]?.name;
80+
obj[key] = cleanCredentials(obj[key]);
81+
} else {
82+
obj[key] = `<${placeholder ?? key}>`;
83+
}
84+
}
85+
86+
return obj;
87+
}
7588

76-
// scrub credentials from code snippets
77-
const cleanedAuth = {
78-
...clonedAuth,
79-
data: cleanCredentials(clonedAuth.data),
80-
};
89+
return {
90+
...clonedAuth,
91+
data: cleanCredentials(clonedAuth.data),
92+
};
93+
})()
94+
: auth;
8195

82-
// Create a Postman request object using cleanedAuth
96+
// Create a Postman request object using cleanedAuth or original auth
8397
const cleanedPostmanRequest = buildPostmanRequest(postman, {
8498
queryParams,
8599
pathParams,

‎packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/index.tsx

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77

88
import React from "react";
99

10+
import { useDoc } from "@docusaurus/plugin-content-docs/client";
1011
import CodeSnippets from "@theme/ApiExplorer/CodeSnippets";
1112
import Request from "@theme/ApiExplorer/Request";
1213
import Response from "@theme/ApiExplorer/Response";
@@ -21,6 +22,9 @@ function ApiExplorer({
2122
item: NonNullable<ApiItem>;
2223
infoPath: string;
2324
}) {
25+
const metadata = useDoc();
26+
const { mask_credentials } = metadata.frontMatter;
27+
2428
const postman = new sdk.Request(
2529
item.postman
2630
? sdk.Request.isRequest(item.postman)
@@ -36,6 +40,7 @@ function ApiExplorer({
3640
<CodeSnippets
3741
postman={postman}
3842
codeSamples={(item as any)["x-codeSamples"] ?? []}
43+
maskCredentials={mask_credentials}
3944
/>
4045
)}
4146
<Request item={item} />

0 commit comments

Comments
 (0)