Using createSchemaPageMD in the markdownGenerators config crashes the CLI

[iaacosta]

Describe the bug

When defining the createSchemaPageMD function in the config file, the CLI crashes with an error when trying to regenerate the docs.

Expected behavior

The CLI should not crash, but rather execute the defined function when rendering the markdown content.

Current behavior

When trying to define the createSchemaPageMD within the plugin config (under config.<my-api-name>.markdownGenerators.createSchemaPageMD), the app crashes. It produces the following error:

[Error [ValidationError]: "config.mycompany.markdownGenerators.createSchemaPageMD" is not allowed]

Full exception

[Error [ValidationError]: "config.mycompany.markdownGenerators.createSchemaPageMD" is not allowed] {
  _original: {
    id: 'api',
    docsPluginId: 'classic',
    config: {
      mycompany: {
        specPath: './api/mycompanyapi.yaml',
        outputDir: 'docs/api/resources',
        markdownGenerators: { createSchemaPageMD: [Function: schemaPageGenerator] },
        sidebarOptions: {
          groupPathsBy: 'tag',
          sidebarGenerators: { createDocItem: [Function: sidebarItemGenerator] }
        }
      }
    }
  },
  details: [
    {
      message: '"config.mycompany.markdownGenerators.createSchemaPageMD" is not allowed',
      path: [ 'config', 'mycompany', 'markdownGenerators', 'createSchemaPageMD' ],
      type: 'object.unknown',
      context: {
        child: 'createSchemaPageMD',
        label: 'config.mycompany.markdownGenerators.createSchemaPageMD',
        value: [Function: schemaPageGenerator],
        key: 'createSchemaPageMD'
      }
    }
  ]
}

Possible solution

Upon inspecting the codebase, it appears that a validator might be missing in the markdownGenerators:

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

Lines 23 to 27 in 7fe9da2

	const markdownGenerators = Joi.object({
	createApiPageMD: Joi.function(),
	createInfoPageMD: Joi.function(),
	createTagPageMD: Joi.function(),
	});

At least when testing locally, just adding a createSchemaPageMD: Joi.function(), seems to work, though I'm not sure if this affects any other features.

Steps to reproduce

1. Initialize a new docusaurus project with the latest version

    npx create-docusaurus@latest sample classic --typescript
   

2. Change directory to the project and install docusaurus-plugin-openapi-docs

   cd sample
   npm i docusaurus-plugin-openapi-docs docusaurus-theme-openapi-docs
   

3. Configure a dummy API as shown in the official docs, and add the createSchemaPageMD markdown generator

   Configuration

   // ...
   
   const config: Config = {
     // ...
     plugins: [
       [
         'docusaurus-plugin-openapi-docs',
         {
           id: 'api',
           docsPluginId: 'classic',
           config: {
             petstore: {
               specPath:
              'https://raw.githubusercontent.com/PaloAltoNetworks/docusaurus-openapi-docs/refs/heads/main/demo/examples/   petstore.yaml',
               outputDir: 'docs/petstore',
               markdownGenerators: {
                 createSchemaPageMD() {
                   return '# Hello schema';
                 },
               },
               sidebarOptions: {
                 groupPathsBy: 'tag',
               },
             } satisfies OpenApiPlugin.Options,
           },
         },
       ],
     ],
     themes: ['docusaurus-theme-openapi-docs'],
     // ...
   };

4. Run the generate API docs command (or start the server, both should throw the exception)

   npm run docusaurus gen-api-docs all
   

Context

I'm trying to add a code snippet next to the schema definition, containing an example response of the schema:

Your Environment

• Version used: 4.1.0
• Environment name and version (e.g. Chrome 59, node.js 5.4, python 3.7.3): NodeJS 20.17.0
• Operating System and version (desktop or mobile): Desktop, OSX Ventura 13.3.1
• Link to your project: N/A

Let me know if I didn't see something, happy to help you guys with a PR if needed.

[robbieaverill]

I can confirm that #1001 fixes this issue, using the suggested possible solution in this issue.

[iaacosta]

Just confirmed it too! Thanks @sserrata for the fix and also for implementing the example within the schema definitions.

Closing the issue as it is solved and will be coming in next release