feat: add support to info, and tag, and schema custom tamplates

[fernandoseguim]

Description

Added support for custom templates for different content types in the Docusaurus OpenAPI Docs plugin. The changes include:

1. Creation of custom Mustache templates for:

   • APIs (api.mustache)
   • Info pages (info.mustache)
   • Schemas (schema.mustache)
   • Tags (tag.mustache)

2. Updated Docusaurus configuration to support custom templates

3. Added necessary types and interfaces to support template functionality

Motivation and Context

Currently, the plugin only supports custom templates for generating markdown files for API endpoints. This limitation makes it difficult for users to customize other aspects of the documentation, such as info pages, schemas, and tags. By extending template support to these additional content types, users can now have full control over the documentation generation process and maintain consistency across all documentation sections.

How Has This Been Tested?

The changes were tested through:

1. Verification of correct documentation generation using the new templates
2. Validation of compatibility with existing configuration
3. Integration testing with Docusaurus

Types of changes

• New feature (non-breaking change which adds functionality)

Checklist

• I have updated the documentation accordingly
• I have read the CONTRIBUTING document
• I have added tests to cover my changes if appropriate
• All new and existing tests passed

The changes are non-breaking and add a new feature that provides greater flexibility in customizing the generated documentation.

[github-actions]

Visit the preview URL for this PR (updated for commit 6384916):

https://docusaurus-openapi-36b86--pr1122-kpluffsy.web.app

_{(expires Wed, 14 May 2025 14:28:01 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

_{Sign: bf293780ee827f578864d92193b8c2866acd459f}

[sserrata]

Thanks @fernandoseguim...

For some reason, the infoTemplate doesn't appear to be working as expected...at least I am not seeing "Hello World!" in the Introduction doc/page.

[fernandoseguim]

@sserrata thanks for your feedback. It worked well in my tests, but please give me a day to double-check on my side.

[fernandoseguim]

@sserrata the Introduction page (doc/page) is indeed being affected by the template that references api.mustache. I removed a condition in this commit to fix this. I tested it locally and didn’t notice any side effects in other places.

I was expecting the same behavior to apply to the category page (/category/petstore-api), but that doesn't seem to be the case. I couldn’t locate where infoTemplate is actually being used here.

My intention is to customize (or hide) the dynamically generated cards. Maybe I’m looking in the wrong place. Do you have any suggestions?

[fernandoseguim]

Hi @sserrata — I’ve run a few more tests and everything’s working just as expected.

For now, I’m pulling the package directly into my project while we wait for the official release.
Do you have any idea when this PR might be included in a release?

Thanks!

https://hub.guardia.finance/en/docs/api/lke/introducao

[sserrata]

Hi @fernandoseguim, on second inspection, I think we introduced a regression with this PR, concerning info pages...

With the previous behavior, we only applied the infoMdTemplate when categorySourceLink was set to "info". With the changes in your PR, the infoMdTemplate will always be applied, which can result in build errors when then info page is not used as a category source:

Error: Can't render static file for pathname "/access/api/adem/autonomous-dem-api/"
            at generateStaticFile (/Users/sserrata/projects/panw/pan.dev/node_modules/@docusaurus/core/lib/ssg/ssg.js:167:15)
            at async /Users/sserrata/projects/panw/pan.dev/node_modules/p-map/index.js:57:22 {
          [cause]: Error: /access/api/adem/autonomous-dem-api/ is not associated with a category. useCurrentSidebarCategory() should only be used on category index pages.

I'm still investigating but my initial thought is to:

• Revert the sidebarOptions?.categoryLinkSource === "info" conditional check
• Create another template to be used in the case where categoryLinkSource is "info" but no info template is provided by the user

This should allow us to keep your changes while maintaining backward compatibility.