From bc6e70ae2a972c429f486272451d00a7f45fdfd8 Mon Sep 17 00:00:00 2001 From: Michael Perrotte Date: Sat, 8 Nov 2025 01:24:11 -0500 Subject: [PATCH 01/12] feat: add new configuration types --- packages/docusaurus-plugin-openapi-docs/src/types.ts | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/packages/docusaurus-plugin-openapi-docs/src/types.ts b/packages/docusaurus-plugin-openapi-docs/src/types.ts index 0c65e4360..9829303c0 100644 --- a/packages/docusaurus-plugin-openapi-docs/src/types.ts +++ b/packages/docusaurus-plugin-openapi-docs/src/types.ts @@ -35,6 +35,7 @@ export interface APIOptions { specPath: string; outputDir: string; template?: string; + templateGenerators?: TemplateGenerators; infoTemplate?: string; tagTemplate?: string; schemaTemplate?: string; @@ -62,6 +63,13 @@ export interface MarkdownGenerator { createSchemaPageMD?: (pageData: SchemaPageMetadata) => string; } +export interface TemplateGenerators { + createIntroTemplateMD?: () => string; + createInfoTemplateMD?: () => string; + createTagTemplateMD?: () => string; + createSchemaTemplateMD?: () => string; +} + export type ApiDocItemGenerator = ( item: ApiPageMetadata | SchemaPageMetadata, context: { sidebarOptions: SidebarOptions; basePath: string } From 529f99f6477cbcd14be7219a6c8ae6324ddaa050 Mon Sep 17 00:00:00 2001 From: Michael Perrotte Date: Sat, 8 Nov 2025 01:24:27 -0500 Subject: [PATCH 02/12] feat: add template defaults --- .../src/markdown/templates.ts | 96 +++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 packages/docusaurus-plugin-openapi-docs/src/markdown/templates.ts diff --git a/packages/docusaurus-plugin-openapi-docs/src/markdown/templates.ts b/packages/docusaurus-plugin-openapi-docs/src/markdown/templates.ts new file mode 100644 index 000000000..21c2911a4 --- /dev/null +++ b/packages/docusaurus-plugin-openapi-docs/src/markdown/templates.ts @@ -0,0 +1,96 @@ +export const introMdTemplateDefault = `--- +id: {{{id}}} +title: "{{{title}}}" +description: "{{{frontMatter.description}}}" +{{^api}} +sidebar_label: Introduction +{{/api}} +{{#api}} +sidebar_label: "{{{title}}}" +{{/api}} +{{^api}} +sidebar_position: 0 +{{/api}} +hide_title: true +{{#api}} +hide_table_of_contents: true +{{/api}} +{{#json}} +api: {{{json}}} +{{/json}} +{{#api.method}} +sidebar_class_name: "{{{api.method}}} api-method" +{{/api.method}} +{{#infoPath}} +info_path: {{{infoPath}}} +{{/infoPath}} +custom_edit_url: null +{{#frontMatter.proxy}} +proxy: {{{frontMatter.proxy}}} +{{/frontMatter.proxy}} +{{#frontMatter.hide_send_button}} +hide_send_button: true +{{/frontMatter.hide_send_button}} +{{#frontMatter.show_extensions}} +show_extensions: true +{{/frontMatter.show_extensions}} +{{#frontMatter.mask_credentials_disabled}} +mask_credentials: false +{{/frontMatter.mask_credentials_disabled}} +--- + +{{{markdown}}} + `; + +export const infoMdTemplateDefault = `--- +id: {{{id}}} +title: "{{{title}}}" +description: "{{{frontMatter.description}}}" +sidebar_label: "{{{title}}}" +hide_title: true +custom_edit_url: null +--- + +{{{markdown}}} + +\`\`\`mdx-code-block +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + + +\`\`\` + `; + +export const tagMdTemplateDefault = `--- +id: {{{id}}} +title: "{{{frontMatter.description}}}" +description: "{{{frontMatter.description}}}" +custom_edit_url: null +--- + +{{{markdown}}} + +\`\`\`mdx-code-block +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + + +\`\`\` + `; + +export const schemaMdTemplateDefault = `---; +id: {{{id}}} +title: "{{{title}}}" +description: "{{{frontMatter.description}}}" +sidebar_label: "{{{title}}}" +hide_title: true +{{#schema}} +hide_table_of_contents: true +{{/schema}} +schema: true +sample: {{{frontMatter.sample}}} +custom_edit_url: null +--- + +{{{markdown}}} + `; From 903804aa39b328c9ca55fb3f39d3895ad26b0a72 Mon Sep 17 00:00:00 2001 From: Michael Perrotte Date: Sat, 8 Nov 2025 01:25:02 -0500 Subject: [PATCH 03/12] feat: update template logic to use generators --- .../src/index.ts | 113 ++++-------------- 1 file changed, 20 insertions(+), 93 deletions(-) diff --git a/packages/docusaurus-plugin-openapi-docs/src/index.ts b/packages/docusaurus-plugin-openapi-docs/src/index.ts index 570fcf2b5..f62f5a023 100644 --- a/packages/docusaurus-plugin-openapi-docs/src/index.ts +++ b/packages/docusaurus-plugin-openapi-docs/src/index.ts @@ -21,6 +21,13 @@ import { createSchemaPageMD, createTagPageMD, } from "./markdown"; +import { + introMdTemplateDefault, + infoMdTemplateDefault, + tagMdTemplateDefault, + schemaMdTemplateDefault, + infoMdTemplateDefault, +} from "./markdown/templates"; import { processOpenapiFiles, readOpenapiFiles } from "./openapi"; import { OptionsSchema } from "./options"; import generateSidebarSlice from "./sidebars"; @@ -117,6 +124,7 @@ export default function pluginOpenAPIDocs( specPath, outputDir, template, + templateGenerators, infoTemplate, tagTemplate, schemaTemplate, @@ -198,108 +206,27 @@ export default function pluginOpenAPIDocs( const mdTemplate = template ? fs.readFileSync(template).toString() - : `--- -id: {{{id}}} -title: "{{{title}}}" -description: "{{{frontMatter.description}}}" -{{^api}} -sidebar_label: Introduction -{{/api}} -{{#api}} -sidebar_label: "{{{title}}}" -{{/api}} -{{^api}} -sidebar_position: 0 -{{/api}} -hide_title: true -{{#api}} -hide_table_of_contents: true -{{/api}} -{{#json}} -api: {{{json}}} -{{/json}} -{{#api.method}} -sidebar_class_name: "{{{api.method}}} api-method" -{{/api.method}} -{{#infoPath}} -info_path: {{{infoPath}}} -{{/infoPath}} -custom_edit_url: null -{{#frontMatter.proxy}} -proxy: {{{frontMatter.proxy}}} -{{/frontMatter.proxy}} -{{#frontMatter.hide_send_button}} -hide_send_button: true -{{/frontMatter.hide_send_button}} -{{#frontMatter.show_extensions}} -show_extensions: true -{{/frontMatter.show_extensions}} -{{#frontMatter.mask_credentials_disabled}} -mask_credentials: false -{{/frontMatter.mask_credentials_disabled}} ---- - -{{{markdown}}} - `; + : templateGenerators?.createIntroTemplateMD + ? templateGenerators.createIntroTemplateMD() + : introMdTemplateDefault; const infoMdTemplate = infoTemplate ? fs.readFileSync(infoTemplate).toString() - : `--- -id: {{{id}}} -title: "{{{title}}}" -description: "{{{frontMatter.description}}}" -sidebar_label: "{{{title}}}" -hide_title: true -custom_edit_url: null ---- - -{{{markdown}}} - -\`\`\`mdx-code-block -import DocCardList from '@theme/DocCardList'; -import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; - - -\`\`\` - `; + : templateGenerators?.createInfoTemplateMD + ? templateGenerators.createInfoTemplateMD() + : infoMdTemplateDefault; const tagMdTemplate = tagTemplate ? fs.readFileSync(tagTemplate).toString() - : `--- -id: {{{id}}} -title: "{{{frontMatter.description}}}" -description: "{{{frontMatter.description}}}" -custom_edit_url: null ---- - -{{{markdown}}} - -\`\`\`mdx-code-block -import DocCardList from '@theme/DocCardList'; -import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; - - -\`\`\` - `; + : templateGenerators?.createTagTemplateMD + ? templateGenerators.createTagTemplateMD() + : tagMdTemplateDefault; const schemaMdTemplate = schemaTemplate ? fs.readFileSync(schemaTemplate).toString() - : `--- -id: {{{id}}} -title: "{{{title}}}" -description: "{{{frontMatter.description}}}" -sidebar_label: "{{{title}}}" -hide_title: true -{{#schema}} -hide_table_of_contents: true -{{/schema}} -schema: true -sample: {{{frontMatter.sample}}} -custom_edit_url: null ---- - -{{{markdown}}} - `; + : templateGenerators?.createSchemaTemplateMD + ? templateGenerators.createSchemaTemplateMD() + : schemaMdTemplateDefault; const apiPageGenerator = markdownGenerators?.createApiPageMD ?? createApiPageMD; From 88bc79d67259763c9a75b20777b651dc92f624bf Mon Sep 17 00:00:00 2001 From: Michael Perrotte Date: Sat, 8 Nov 2025 01:41:26 -0500 Subject: [PATCH 04/12] fix: remove duplicated import --- packages/docusaurus-plugin-openapi-docs/src/index.ts | 1 - 1 file changed, 1 deletion(-) diff --git a/packages/docusaurus-plugin-openapi-docs/src/index.ts b/packages/docusaurus-plugin-openapi-docs/src/index.ts index f62f5a023..34d82072d 100644 --- a/packages/docusaurus-plugin-openapi-docs/src/index.ts +++ b/packages/docusaurus-plugin-openapi-docs/src/index.ts @@ -26,7 +26,6 @@ import { infoMdTemplateDefault, tagMdTemplateDefault, schemaMdTemplateDefault, - infoMdTemplateDefault, } from "./markdown/templates"; import { processOpenapiFiles, readOpenapiFiles } from "./openapi"; import { OptionsSchema } from "./options"; From 4975f0e32192597b9886989888e78cc665aa8fa2 Mon Sep 17 00:00:00 2001 From: Michael Perrotte Date: Sat, 8 Nov 2025 16:17:59 -0500 Subject: [PATCH 05/12] chore: update docs in demo - update intro page with section on template generators --- demo/docs/intro.mdx | 61 ++++++++++++++++++++++++++++++++++----------- 1 file changed, 46 insertions(+), 15 deletions(-) diff --git a/demo/docs/intro.mdx b/demo/docs/intro.mdx index d4779c3f7..f39bf41a7 100644 --- a/demo/docs/intro.mdx +++ b/demo/docs/intro.mdx @@ -29,7 +29,6 @@ OpenAPI plugin for generating API reference docs in Docusaurus v3. [![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/HEAD/LICENSE) [![npm latest package](https://img.shields.io/npm/v/docusaurus-plugin-openapi-docs/latest.svg)](https://www.npmjs.com/package/docusaurus-plugin-openapi-docs) [![npm downloads](https://img.shields.io/npm/dm/docusaurus-plugin-openapi-docs.svg)](https://www.npmjs.com/package/docusaurus-plugin-openapi-docs) [![npm canary package](https://img.shields.io/npm/v/docusaurus-plugin-openapi-docs/canary.svg)](https://www.npmjs.com/package/docusaurus-plugin-openapi-docs) [![npm beta package](https://img.shields.io/npm/v/docusaurus-plugin-openapi-docs/beta.svg)](https://www.npmjs.com/package/docusaurus-plugin-openapi-docs) -