From ba48227af27cd27936df1bf9f7e0c364e9c29f4f Mon Sep 17 00:00:00 2001 From: Fernando Seguim Date: Fri, 28 Mar 2025 18:30:17 -0300 Subject: [PATCH 1/3] feat: add support to info, and tag, and schema custom tamplates --- demo/docusaurus.config.ts | 5 ++++- demo/{ => templates}/api.mustache | 0 demo/templates/info.mustache | 12 ++++++++++++ demo/templates/schema.mustache | 17 +++++++++++++++++ demo/templates/tag.mustache | 10 ++++++++++ .../docusaurus-plugin-openapi-docs/src/index.ts | 15 ++++++++++++--- .../src/options.ts | 3 +++ .../docusaurus-plugin-openapi-docs/src/types.ts | 3 +++ 8 files changed, 61 insertions(+), 4 deletions(-) rename demo/{ => templates}/api.mustache (100%) create mode 100644 demo/templates/info.mustache create mode 100644 demo/templates/schema.mustache create mode 100644 demo/templates/tag.mustache diff --git a/demo/docusaurus.config.ts b/demo/docusaurus.config.ts index bd6dbeba6..15cf61e33 100644 --- a/demo/docusaurus.config.ts +++ b/demo/docusaurus.config.ts @@ -297,7 +297,10 @@ const config: Config = { groupPathsBy: "tag", categoryLinkSource: "tag", }, - template: "api.mustache", // Customize API MDX with mustache template + template: "templates/api.mustache", // Customize API MDX with mustache template + infoTemplate: "templates/info.mustache", + tagTemplate: "templates/tag.mustache", + schemaTemplate: "templates/schema.mustache", downloadUrl: "/petstore.yaml", hideSendButton: false, showSchemas: true, diff --git a/demo/api.mustache b/demo/templates/api.mustache similarity index 100% rename from demo/api.mustache rename to demo/templates/api.mustache diff --git a/demo/templates/info.mustache b/demo/templates/info.mustache new file mode 100644 index 000000000..1836b913f --- /dev/null +++ b/demo/templates/info.mustache @@ -0,0 +1,12 @@ +--- +id: {{{id}}} +title: "{{{title}}}" +description: "{{{frontMatter.description}}}" +sidebar_label: "{{{title}}}" +hide_title: true +custom_edit_url: null +--- + +{{{markdown}}} + +Hello World! \ No newline at end of file diff --git a/demo/templates/schema.mustache b/demo/templates/schema.mustache new file mode 100644 index 000000000..080c65dc6 --- /dev/null +++ b/demo/templates/schema.mustache @@ -0,0 +1,17 @@ +--- +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}}} + +Hello World! \ No newline at end of file diff --git a/demo/templates/tag.mustache b/demo/templates/tag.mustache new file mode 100644 index 000000000..da7e77730 --- /dev/null +++ b/demo/templates/tag.mustache @@ -0,0 +1,10 @@ +--- +id: {{{id}}} +title: "{{{frontMatter.description}}}" +description: "{{{frontMatter.description}}}" +custom_edit_url: null +--- + +{{{markdown}}} + +Hello World! \ No newline at end of file diff --git a/packages/docusaurus-plugin-openapi-docs/src/index.ts b/packages/docusaurus-plugin-openapi-docs/src/index.ts index 15d1206f1..002d07d7f 100644 --- a/packages/docusaurus-plugin-openapi-docs/src/index.ts +++ b/packages/docusaurus-plugin-openapi-docs/src/index.ts @@ -117,6 +117,9 @@ export default function pluginOpenAPIDocs( specPath, outputDir, template, + infoTemplate, + tagTemplate, + schemaTemplate, markdownGenerators, downloadUrl, sidebarOptions, @@ -236,7 +239,9 @@ show_extensions: true {{{markdown}}} `; - const infoMdTemplate = `--- + const infoMdTemplate = infoTemplate + ? fs.readFileSync(infoTemplate).toString() + : `--- id: {{{id}}} title: "{{{title}}}" description: "{{{frontMatter.description}}}" @@ -255,7 +260,9 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; \`\`\` `; - const tagMdTemplate = `--- + const tagMdTemplate = tagTemplate + ? fs.readFileSync(tagTemplate).toString() + : `--- id: {{{id}}} title: "{{{frontMatter.description}}}" description: "{{{frontMatter.description}}}" @@ -272,7 +279,9 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; \`\`\` `; - const schemaMdTemplate = `--- + const schemaMdTemplate = schemaTemplate + ? fs.readFileSync(schemaTemplate).toString() + : `--- id: {{{id}}} title: "{{{title}}}" description: "{{{frontMatter.description}}}" diff --git a/packages/docusaurus-plugin-openapi-docs/src/options.ts b/packages/docusaurus-plugin-openapi-docs/src/options.ts index ff114de7f..3c46e27f5 100644 --- a/packages/docusaurus-plugin-openapi-docs/src/options.ts +++ b/packages/docusaurus-plugin-openapi-docs/src/options.ts @@ -39,6 +39,9 @@ export const OptionsSchema = Joi.object({ proxy: Joi.string(), outputDir: Joi.string().required(), template: Joi.string(), + infoTemplate: Joi.string(), + tagTemplate: Joi.string(), + schemaTemplate: Joi.string(), downloadUrl: Joi.string(), hideSendButton: Joi.boolean(), showExtensions: Joi.boolean(), diff --git a/packages/docusaurus-plugin-openapi-docs/src/types.ts b/packages/docusaurus-plugin-openapi-docs/src/types.ts index 43367bbaa..721aea14d 100644 --- a/packages/docusaurus-plugin-openapi-docs/src/types.ts +++ b/packages/docusaurus-plugin-openapi-docs/src/types.ts @@ -35,6 +35,9 @@ export interface APIOptions { specPath: string; outputDir: string; template?: string; + infoTemplate?: string; + tagTemplate?: string; + schemaTemplate?: string; downloadUrl?: string; hideSendButton?: boolean; showExtensions?: boolean; From 6eeb7bef17e5daca681adca7c2dba2becb009701 Mon Sep 17 00:00:00 2001 From: Fernando Seguim Date: Sat, 12 Apr 2025 21:51:32 -0300 Subject: [PATCH 2/3] docs: enhance template samples --- demo/templates/api.mustache | 14 +++++++++++++- demo/templates/info.mustache | 12 +++++++++++- demo/templates/schema.mustache | 12 +++++++++++- demo/templates/tag.mustache | 12 +++++++++++- 4 files changed, 46 insertions(+), 4 deletions(-) diff --git a/demo/templates/api.mustache b/demo/templates/api.mustache index 9a78cab49..aa1e66166 100644 --- a/demo/templates/api.mustache +++ b/demo/templates/api.mustache @@ -36,4 +36,16 @@ show_extensions: true {{/frontMatter.show_extensions}} --- -{{{markdown}}} \ No newline at end of file +This is a Custom Api Page Generated by docusaurus-openapi-docs using `api.mustache` template + +
+
+
+ +{{{markdown}}} + +
+
+
+ +This is a Custom Api Page Generated by docusaurus-openapi-docs using `api.mustache` template \ No newline at end of file diff --git a/demo/templates/info.mustache b/demo/templates/info.mustache index 1836b913f..3db441945 100644 --- a/demo/templates/info.mustache +++ b/demo/templates/info.mustache @@ -7,6 +7,16 @@ hide_title: true custom_edit_url: null --- +This is a Custom Info Page Generated by docusaurus-openapi-docs using `info.mustache` template + +
+
+
+ {{{markdown}}} -Hello World! \ No newline at end of file +
+
+
+ +This is a Custom Info Page Generated by docusaurus-openapi-docs using `info.mustache` template \ No newline at end of file diff --git a/demo/templates/schema.mustache b/demo/templates/schema.mustache index 080c65dc6..274323bca 100644 --- a/demo/templates/schema.mustache +++ b/demo/templates/schema.mustache @@ -12,6 +12,16 @@ sample: {{{frontMatter.sample}}} custom_edit_url: null --- +This is a Custom Schema Page Generated by docusaurus-openapi-docs using `schema.mustache` template + +
+
+
+ {{{markdown}}} -Hello World! \ No newline at end of file +
+
+
+ +This is a Custom Schema Page Generated by docusaurus-openapi-docs using `schema.mustache` template \ No newline at end of file diff --git a/demo/templates/tag.mustache b/demo/templates/tag.mustache index da7e77730..b73b60a81 100644 --- a/demo/templates/tag.mustache +++ b/demo/templates/tag.mustache @@ -5,6 +5,16 @@ description: "{{{frontMatter.description}}}" custom_edit_url: null --- +This is a Custom Tag Page Generated by docusaurus-openapi-docs using `tag.mustache` template + +
+
+
+ {{{markdown}}} -Hello World! \ No newline at end of file +
+
+
+ +This is a Custom Tag Page Generated by docusaurus-openapi-docs using `tag.mustache` template \ No newline at end of file From 63849163571db41b4e4596a28095a12a1147ba2f Mon Sep 17 00:00:00 2001 From: Fernando Seguim Date: Sat, 12 Apr 2025 22:16:55 -0300 Subject: [PATCH 3/3] fix: ensure infoTemplate is used to generate the Introduction page --- .../docusaurus-plugin-openapi-docs/src/index.ts | 17 +++++------------ 1 file changed, 5 insertions(+), 12 deletions(-) diff --git a/packages/docusaurus-plugin-openapi-docs/src/index.ts b/packages/docusaurus-plugin-openapi-docs/src/index.ts index 002d07d7f..7fd6e0f2b 100644 --- a/packages/docusaurus-plugin-openapi-docs/src/index.ts +++ b/packages/docusaurus-plugin-openapi-docs/src/index.ts @@ -380,21 +380,14 @@ custom_edit_url: null } } - // TODO: determine if we actually want/need this if (item.type === "info") { if (!fs.existsSync(`${outputDir}/${item.id}.info.mdx`)) { try { - sidebarOptions?.categoryLinkSource === "info" // Only use utils template if set to "info" - ? fs.writeFileSync( - `${outputDir}/${item.id}.info.mdx`, - utils, - "utf8" - ) - : fs.writeFileSync( - `${outputDir}/${item.id}.info.mdx`, - view, - "utf8" - ); + fs.writeFileSync( + `${outputDir}/${item.id}.info.mdx`, + utils, + "utf8" + ); console.log( chalk.green( `Successfully created "${outputDir}/${item.id}.info.mdx"`