paloaltonetworks / docusaurus-openapi-docs

🦝 OpenAPI plugin for generating API reference docs in Docusaurus v2.

Docusaurus OpenAPI Doc Generator

OpenAPI plugin for generating API reference docs in Docusaurus v2.

---

Overview

The docusaurus-plugin-openapi-docs package extends the Docusaurus CLI with commands for generating MDX using the OpenAPI specification as the source. The resulting MDX is fully compatible with plugin-content-docs and can be used to render beautiful reference API docs by setting docItemComponent to @theme/ApiItem, a custom component included in the docusaurus-theme-openapi-docs theme.

Key Features:

• Compatible: Works with Swagger 2.0 and OpenAPI 3.0.
• Fast: Convert large OpenAPI specs into MDX docs in seconds. 🔥
• Stylish: Based on the same Infima styling framework that powers the Docusaurus UI.
• Flexible: Supports single, multi and even micro OpenAPI specs.

Compatibility Matrix

Docusaurus OpenAPI Docs	Docusaurus
3.0.0-beta.x (beta)	3.0.1 - 3.1.1
2.0.x (current)	2.4.1 - 2.4.3
1.7.3 (legacy)	2.0.1 - 2.2.0

Bootstrapping from Template (new Docusaurus site)

Run the following to bootstrap a Docsaurus v2 site (classic theme) with docusaurus-openapi-docs:

npx [email protected] my-website --package-manager yarn

When prompted to select a template choose Git repository.

Template Repository URL:

https://github.com/PaloAltoNetworks/docusaurus-template-openapi-docs.git

When asked how the template repo should be cloned choose "copy" (unless you know better).

cd my-website
yarn start

Installation (existing Docusaurus site)

Plugin:

yarn add docusaurus-plugin-openapi-docs

Theme:

yarn add docusaurus-theme-openapi-docs

Configuring docusaurus.config.js (Plugin and theme usage)

Here is an example of properly configuring docusaurus.config.js file for docusaurus-plugin-openapi-docs and docusaurus-theme-openapi-docs usage.

// docusaurus.config.js

{
  presets: [
    [
      "classic",
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        docs: {
          sidebarPath: require.resolve("./sidebars.js"),
          editUrl:
            "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/",
          docLayoutComponent: "@theme/DocPage",
          docItemComponent: "@theme/ApiItem" // derived from docusaurus-theme-openapi-docs
        },
        blog: {
          showReadingTime: true,
          editUrl:
            "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/"
        },
        theme: {
          customCss: require.resolve("./src/css/custom.css")
        }
      })
    ]
  ],

  plugins: [
    [
      'docusaurus-plugin-openapi-docs',
      {
        id: "api", // plugin id
        docsPluginId: "classic", // id of plugin-content-docs or preset for rendering docs
        config: {
          petstore: { // the <id> referenced when running CLI commands
            specPath: "examples/petstore.yaml", // path to OpenAPI spec, URLs supported
            outputDir: "api/petstore", // output directory for generated files
            sidebarOptions: { // optional, instructs plugin to generate sidebar.js
              groupPathsBy: "tag", // group sidebar items by operation "tag"
            },
          },
          burgers: {
            specPath: "examples/food/burgers/openapi.yaml",
            outputDir: "api/food/burgers",
          }
        }
      },
    ]
  ],
  themes: ["docusaurus-theme-openapi-docs"], // export theme components
}

Note: You may optionally configure a dedicated @docusaurus/plugin-content-docs instance for use with docusaurus-theme-openapi-docs by setting docItemComponent to @theme/ApiItem.

Plugin Configuration Options

The docusaurus-plugin-openapi-docs plugin can be configured with the following options:

Name	Type	Default	Description
id	string	null	A unique plugin ID.
docsPlugin	string	@docusaurus/plugin-content-docs	The plugin used to render the OpenAPI docs (ignored if the plugin instance referenced by docsPluginId is a preset).
docsPluginId	string	null	The plugin ID associated with the preset or configured docsPlugin instance used to render the OpenAPI docs (e.g. "your-plugin-id", "classic", "default").

config

config can be configured with the following options:

Name	Type	Default	Description
specPath	string	null	Designated URL or path to the source of an OpenAPI specification file or directory of multiple OpenAPI specification files.
ouputDir	string	null	Desired output path for generated MDX and sidebar files.
proxy	string	null	Optional: Proxy URL to prepend to base URL when performing API requests from browser.
template	string	null	Optional: Customize MDX content with a desired template.
downloadUrl	string	null	Optional: Designated URL for downloading OpenAPI specification. (requires info section/doc)
hideSendButton	boolean	null	Optional: If set to true, hides the "Send API Request" button in API demo panel
showExtensions	boolean	null	Optional: If set to true, renders operation-level vendor-extensions in description.
sidebarOptions	object	null	Optional: Set of options for sidebar configuration. See below for a list of supported options.
version	string	null	Optional: Version assigned to single or micro-spec API specified in specPath.
label	string	null	Optional: Version label used when generating version selector dropdown menu.
baseUrl	string	null	Optional: Version base URL used when generating version selector dropdown menu.
versions	object	null	Optional: Set of options for versioning configuration. See below for a list of supported options.
markdownGenerators	object	null	Optional: Customize MDX content with a set of options for specifying markdown generator functions. See below for a list of supported options.
showSchemas	boolean	null	Optional: If set to true, generates schema pages and adds them to the sidebar.

sidebarOptions can be configured with the following options:

Name	Type	Default	Description
groupPathsBy	string	null	Organize and group sidebar slice by specified option. Note: Currently, groupPathsBy only contains support for grouping by tag and tagGroup.
categoryLinkSource	string	null	Defines what source to use for rendering category link pages when grouping paths by tag. The supported options are as follows: tag: Sets the category link config type to generated-index and uses the tag description as the link config description. info: Sets the category link config type to doc and renders the info section as the category link (recommended only for multi/micro-spec scenarios). none: Does not create pages for categories, only groups that can be expanded/collapsed.
sidebarCollapsible	boolean	true	Whether sidebar categories are collapsible by default.
sidebarCollapsed	boolean	true	Whether sidebar categories are collapsed by default.
customProps	object	null	Additional props for customizing a sidebar item.

You may optionally configure a sidebarOptions. In doing so, an individual sidebar.js slice with the configured options will be generated within the respective outputDir.

versions can be configured with the following options:

Name	Type	Default	Description
specPath	string	null	Designated URL or path to the source of an OpenAPI specification file or directory of micro OpenAPI specification files.
ouputDir	string	null	Desired output path for versioned, generated MDX files.
label	string	null	Optional: Version label used when generating version selector dropdown menu.
baseUrl	string	null	Optional: Version base URL used when generating version selector dropdown menu.

All versions will automatically inherit sidebarOptions from the parent/base config.

markdownGenerators

markdownGenerators can be configured with the following options:

Name	Type	Default	Description
createApiPageMD	function	null	Optional: Returns a string of the raw markdown body for API pages. Function type: (pageData: ApiPageMetadata) => string
createInfoPageMD	function	null	Optional: Returns a string of the raw markdown body for info pages. Function type: (pageData: InfoPageMetadata) => string
createTagPageMD	function	null	Optional: Returns a string of the raw markdown body for tag pages. Function type: (pageData: TagPageMetadata) => string
createSchemaPageMD	function	null	Optional: Returns a string of the raw markdown body for schema pages. Function type: (pageData: SchemaPageMetadata) => string

CLI Usage

Usage: docusaurus <command> [options]

Options:
  -V, --version                                            output the version number
  -h, --help                                               display help for command

Commands:
  build [options] [siteDir]                                Build website.
  swizzle [options] [themeName] [componentName] [siteDir]  Wraps or ejects the original theme files into website folder for customization.
  deploy [options] [siteDir]                               Deploy website to GitHub pages.
  start [options] [siteDir]                                Start the development server.
  serve [options] [siteDir]                                Serve website locally.
  clear [siteDir]                                          Remove build artifacts.
  write-translations [options] [siteDir]                   Extract required translations of your site.
  write-heading-ids [options] [siteDir] [files...]         Generate heading ids in Markdown content.
  docs:version <version>                                   Tag a new docs version
  gen-api-docs <id>                                        Generates OpenAPI docs in MDX file format and sidebar.js (if enabled).
  gen-api-docs:version <id:version>                        Generates versioned OpenAPI docs in MDX file format, versions.js and sidebar.js (if enabled).
  clean-api-docs <id>                                      Clears the generated OpenAPI docs MDX files and sidebar.js (if enabled).
  clean-api-docs:version <id:version>                      Clears the versioned, generated OpenAPI docs MDX files, versions.json and sidebar.js (if
                                                           enabled).

Generating OpenAPI Docs

To generate all OpenAPI docs, run the following command from the root directory of your project:

yarn docusaurus gen-api-docs all

This will generate API docs for all of the OpenAPI specification (OAS) files referenced in your docusaurus-plugin-openapi-docs config.

You may also generate OpenAPI docs for a single path or OAS by specifying the unique id:

yarn docusaurus gen-api-docs <id>

Example:

yarn docusaurus gen-api-docs burgers

The example above will only generate API docs relative to burgers.

Cleaning API Docs

To clean/remove all API Docs, run the following command from the root directory of your project:

yarn docusaurus clean-api-docs all

You may also remove a particular set of API docs by specifying the unique id of your desired spec instance.

yarn docusaurus clean-api-docs <id>

Example:

yarn docusaurus clean-api-docs burgers

The example above will remove all API docs relative to burgers.

Versioning OpenAPI docs

To generate all versioned OpenAPI docs, run the following command from the root directory of your project:

yarn docusaurus gen-api-docs:version <id>:all

Example:

yarn docusaurus gen-api-docs:version petstore:all

This will generate API docs for all of the OpenAPI specification (OAS) files referenced in your versions config and will also generate a versions.json file.

Substitue all with a specific version ID to generate/clean a specific version. Generating for all or a specific version ID will automatically update the versions.json file.

Developer Quick Start

Looking to make a contribution? Make sure to checkout out our contributing guide.

After forking the main repository, run the following:

git clone https://github.com/<your account>/docusaurus-openapi-docs.git
cd docusaurus-openapi-docs
yarn
yarn build-packages
yarn watch:demo

Credits

Special thanks to @bourdakos1 (Nick Bourdakos), the author of docusaurus-openapi, which this project is heavily based on.

For more insight into why we decided to completely fork see #47

Contributors

Support

See SUPPORT.md for our support agreement and guidelines.

If you believe you found a bug or have an idea you'd like to suggest you may report an issue or start a discussion.

docusaurus-openapi-docs's Issues

[FR] Ability to customize code snippets and responses.

Is your feature request related to a problem?

Would be great to have the code snippets similar to stoplight. I'm also not seeing the 'Response' but perhaps that's a separate bug.

Describe the solution you'd like

I've attached some images.

Describe alternatives you've considered

I'm trying to figure out how to theme it so it looks more similar to the screenshots. Haven't found a library that generates the client code yet.

[Bug] Specs with no tags throw exception when grouping by tags

Describe the bug

Using groupPathsby: "tags" on a spec with no tags results in the following error:

[ERROR] TypeError: Cannot read properties of undefined (reading 'includes')

Expected behavior

A spec with no tags should use a fallback "UNTAGGED" grouping to handle grouping paths.

Current behavior

See error above.

Possible solution

Reinstate the UNTAGGED group and add additional checks to determine if tags exist before proceeding.

Steps to reproduce

Screenshots

Context

Your Environment

• Version used:
• Environment name and version (e.g. Chrome 59, node.js 5.4, python 3.7.3):
• Operating System and version (desktop or mobile):
• Link to your project:

[Bug] Some schemas not handled when `schemaName` doesn't match the strings "object" or "object[]"

Describe the bug

While creating schema details, sometimes the evaluated schemaName did not match against the following conditions: https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/main/packages/docusaurus-plugin-openapi-docs/src/markdown/createSchemaDetails.ts#L55

I believe this occurs because the conditions only check for the string eval of each schema key and not the typeof the schema itself.

Expected behavior

All schemas should be evaluated, regardless of what the schemaName is.

Current behavior

Only schemaNames with "object" or "object[]" string values are evaluated.

Possible solution

  if (
    schemaName &&
    (typeof schema === "object" ||
      ((typeof schema as any) === "array" && typeof schema[0] === "object"))
  )

[FR] API doc version context switcher

Is your feature request related to a problem?

When implementing versioning, it's easy for a user to forget or overlook which version of an API doc they are looking at. The existing versioning system provides a version dropdown selector but individual API docs lack the context necessary to label what API version it applies to.

Describe the solution you'd like

An API doc "version context switcher" component that can be used to:

• Easily identify the current version you are looking at
• Display and allow the user to easily switch the context to other APIs doc versions the endpoint is supported in

Example:

A component like the one above could possibly fit in the upper-right of each API doc item, above the ApiDemoPanel section. Preferable using the built-in Infima Tabs or Button components.

The current version should be in the active state. The other versions should only be displayed if the endpoint is actually supported in those versions. The latter will likely require an extended API versions metadata object/file to allow for quick lookup and conditional rendering of supported versions.

Describe alternatives you've considered

Not worrying about it. We already have a dropdown selector and version badge in the sidebar.

Additional context

Will share third-party examples of this use case if I find any!

[Documentation] Document CSS necessary for rendering method labels/badges

Describe the problem

Currently, there is no documentation on how to make method labels/badges appear next to API items in the sidebar.

Suggested fix

Document the steps necessary for enabling them.

[FR] Support for documenting webhooks

Is your feature request related to a problem?

Currently, the plugin does not support documenting webhooks.

Describe the solution you'd like

Introduce webhook support, similar to how ReDoc currently handles them:

Describe alternatives you've considered

Not supporting them, since none of our current product APIs include them.

Additional context

OpenAPI 3.1 will make paths optional, which will be another way to imply/support webhook endpoints. To support them today (3.0) I believe we'd have to use vendor extensions:

x-webhooks:
  newPet:
    post:
      summary: New pet
      description: Information about a new pet in the systems
      operationId: newPet
      tags:
        - pet
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Pet"
      responses:
        "200":
          description: Return a 200 status to indicate that the data was received successfully

Security Schema doesn't work in the output

Describe the bug

The authorization form is empty for the authentication-required paths.

Expected behavior

An authorization form with the required header for passing the security parameter.

Current behavior

The authorization form is empty.

Possible solution

Steps to reproduce

1. Use this spec:

{
  "openapi": "3.0.1",
  "info": {
    "title": "Test",
    "description": "Description",
    "termsOfService": "",
    "contact": {
      "email": ""
    },
    "version": "1.1.0"
  },
  "externalDocs": {
    "description": "Find out more about Swagger",
    "url": "http://swagger.io"
  },
  "servers": [
    {
      "url": "https://api.test.url"
    }
  ],
  "paths": {
    "/test": {
      "post": {
        "summary": "test endpoint",
        "operationId": "opt1",
        "requestBody": {
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "required": [
                  "id"
                ],
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "example": "id-uuid"
                  }
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "successful",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TestResp"
                }
              }
            }
          }
        },
        "security": [
          {
            "TestAuth": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "TestResp": {
        "required": [
          "id",
          "name"
        ],
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "id-uuid"
          },
          "name": {
            "type": "string",
            "description": "test name"
          }
        }
      }
    },
    "securitySchemes": {
      "TestAuth": {
        "type": "apiKey",
        "name": "X-Test-Auth-Key",
        "in": "header"
      }
    }
  }
}

2. Run npm run start
3. Click on the authorize button at the top right.
4. Authorization form is empty!

Screenshots

Context

I'm trying to generate the document website from an OpenAPI JSON spec. the authentication method and details are ignored in the compiled version. no authorization form or detail is rendered.

Your Environment

• Version used: 0.4.0
• Environment name and version (e.g. Chrome 59, node.js 5.4, python 3.7.3): Chrome 103
• Operating System and version (desktop or mobile): macOS 12.3
• Link to your project: -

[Community Health Assessment] Changes needed

This issue was opened by a bot called Community Health (PANW) because this repo has failed too many community health checks.

Repo maintainers: Please take the time to fix the issues in the table to reach the target score. These improvements will help others find your work and contribute to it. This issue will update as your score improves until it hits the target score.

Click More info for instructions to fix each item.

Health Check	Pass	Score	More Info
Contains a meaningful README.md file	✅	20 / 20	More info
SUPPORT.md file exists	✅	20 / 20	More info
Repo has a description	✅	15 / 15	More info
Has a recognized open source license	✅	15 / 15	More info
Has a descriptive repo name	✅	15 / 15	More info
Required topics attached to repo	❌	0 / 15	More info
CONTRIBUTING.md file with contribution guidelines	✅	5 / 5	More info
Has custom issue and pull request templates	❌	0 / 5	More info

Current score: 90
Target threshold: 100
Total possible: 110

How do I display request types and show description instead of operationId in my sidebar?

Documentation link

On the example (https://docusaurus-openapi.tryingpan.dev/petstore/update-pet-with-form) the sidebar items display the request type (POST, GET, etc.).

Describe the problem

The docs at https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/main/README.md nor the example configuration at https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/main/demo/docusaurus.config.js show how this sidebar configuration was achieved.

Suggested fix

Document the configuration options for:

1. Determining page display title
2. Showing request types in the sidebar.

[FR] Improve a11y support for `ApiDemoPanel`

Is your feature request related to a problem?

Some elements in the ApiDemoPanel cannot be accessed by keyboard/tab.

Describe the solution you'd like

Apply tabindex: 0 to appropriate elements to ensure highest a11y experience.

Describe alternatives you've considered

n/a

Additional context

Improving a11y not only improves UX but also helps improve SEO.

[FR] Add support for `x-logo` vendor extension

Is your feature request related to a problem?

No, just room for improvement.

Describe the solution you'd like

Ability to support x-logo vendor extension, similar to ReDoc, which could be used to specify a logo to display for the API.

Describe alternatives you've considered

n/a

Additional context

Was thinking we could place it in the intro doc or perhaps even find a way to include it in all API operation doc pages.

https://api.apis.guru/v2/specs/instagram.com/1.0.0/swagger.yaml

[FR] Reverse qualifier expressions to improve readability

Is your feature request related to a problem?

Some of the qualifiers, e.g minLength, maxLength, minItems, etc., result in mathematical expressions including operators like >, <, >=, <=. The issue is that the expressions, although accurate, are not displayed in a natural, intuitive manner:

In the example below, notice the possible values are expressed in "reverse" as "1 ≤ value":

Describe the solution you'd like

Refactor qualifiers as needed to display in a more natural, intuitive manner. For example, "1 <= value" could be more easily understood if it was written as "value >= 1" or simply ">= 1".

Describe alternatives you've considered

n/a

Additional context

I believe ReDoc offers a great example of how to express qualifiers and should be referenced whenever needed.

[Bug] 2.0.0-beta.19 and 2.0.0-beta.20 Breaking Changes

Describe the bug

Docusaurus 2.0.0-beta.19 and 2.0.0-beta.20 introduced breaking changes preventing us from upgrading from 2.0.0-beta.18. This issue will be used for both bug and progress tracking as we work through the issues.

Expected behavior

There should be a viable upgrade path moving from 2.0.0-beta.18 to beta.19 or beta.20.

Current behavior

Currently, we're able to run beta.19 and beta.20 in dev server only - production builds are not possible. The errors suggest possible issue with legacy or incompatible module exports in docusaurus-theme-openapi-docs.

Progress

• Cleanup @ts-ignore throughout project #80
• Address issue with useColorMode hook (ensure calling component is wrapped in Layout)

Error on Docusaurus 2.0.0-rc.1

Describe the bug

This page crashed.
Hook useTabGroupChoice is called outside the .

Expected behavior

Page should load.

Current behavior

Page crashes with above message.

Steps to reproduce

Docusaurus 2.0.0-rc.1, Open API 0.0.0-396

Have cleared and rebuilt API documentation using 396 canary.

[FR] Support for sourcing from URL $ref

Is your feature request related to a problem?

Currently, descriptions sourced from a URL $ref are not rendered properly.

Describe the solution you'd like

The idea would be to support resolving URL refs such that items like descriptions, summary, etc., can be sourced by URL, e.g. from GitHub (raw).

Describe alternatives you've considered

Dereferencing the git/URL-sourced content prior to attempting to generate API docs.

Additional context

Today, if you run the plugin against a spec with URL refs (descriptions) you end up with [object Object]:

[FR] Ability for users to specify server/base URL

Is your feature request related to a problem?

There are some product APIs that generate a unique base URL per customer/tenant, which is not something we could know or predict ahead of time.

Describe the solution you'd like

The ability for users to manually type in their API base URL (server).

Describe alternatives you've considered

n/a

Additional context

Generated code samples directly reference the base URL. One consideration would be how to persist the custom base URL throughout the session or in localStorage.

[FR] index pages for individual tags

Is your feature request related to a problem?

If operations are grouped by tags (groupPathsBy: 'tags' option) the operations are correctly grouped under individual tags but even if the tag has description it is nowhere to be found.

Describe the solution you'd like

It would be perfect if the tag description could be used to generate index pages for individual tags.

Describe alternatives you've considered

The pages can be created manually if necessary such as this page: https://docusaurus-openapi.tryingpan.dev/api/food/burgers/introduction in the demo.

Additional context

Happy to try and contribute if someone would please point me in the right directions 🙏

[Enhancement] Add discriminator support

Carried over from #154

Is your feature request related to a problem?

Currently there is no support for handling discriminators. Moreover, discriminator $ref pointers don't adhere to JSON Schema specification and are thus not resolved by our parser/resolver. This means we will need to resolve discriminator $ref pointers on-demand.

Describe the solution you'd like

• Implement support for discriminators.
• Render schema mappings at the same level as the property we're applying the discriminator to (may necessitate a new UI component or setting the marginLeft to "-2.4rem")
• Leverage the OpenAPIParser class byRef() method to resolve $ref pointers. (Will require instantiating and passing a parser instance for each spec we read in)

Describe alternatives you've considered

Explored using oneOf in place of discriminator but it renders the schema as a child of the property which does not satisfy the requirements.

Additional context

ReDocly has a group write up on this and their ReDoc demo demonstrates the correct implementation: https://redocly.com/docs/resources/discriminator/

[FR] Improve support for micro-specs

Is your feature request related to a problem?

In some cases, OpenAPI docs may be split into multiple micro-specs that, collectively, represent a single, logical API. In those cases, each micro-spec will come with its own info section which will also generate a index.api.mdx. When grouping paths by tag, this can lead to filename collisions as each subsequent index.api.mdx file that is generated will overwrite the one prior.

Describe the solution you'd like

The idea would be to extend support for the micro-spec use case by providing an option for defining when multiple specs should be treated as micro-specs and for creating a convention for generating unique "introduction" docs for each tagged group of paths. Additionally, sidebarOptions should be extended to support setting the category link as the "introduction" doc for each respective group.

Describe alternatives you've considered

• Merging micro-specs into a mono-spec.
• Manually creating the sidebar

Additional context

Longer term, it probably makes more sense to transition micro-specs into a mono-spec but there are some cases where this isn't possible or readily feasible.

Hook useTabGroupChoice is called outside the <TabGroupChoiceProvider>

Describe the bug

Attempting to use the yarn docusaurus gen-api-docs all command to generate docs. Got the base route to render, but when I click on any other route I get a "This page crashed" error with "Hook useTabGroupChoice is called outside the <TabGroupChoiceProvider>."

My config

// @ts-check
// Note: type annotations allow type checking and IDEs autocompletion

const lightCodeTheme = require("prism-react-renderer/themes/github");
const darkCodeTheme = require("prism-react-renderer/themes/dracula");

/** @type {import('@docusaurus/types').Config} */
const config = {
  title: "HailTrace",
  tagline: "Developer Documentation",
  url: "https://developers.hailtrace.com",
  baseUrl: "/",
  onBrokenLinks: "throw",
  onBrokenMarkdownLinks: "warn",
  favicon: "img/favicon.ico",

  // GitHub pages deployment config.
  // If you aren't using GitHub pages, you don't need these.
  // organizationName: "hailtrace", // Usually your GitHub org/user name.
  // projectName: "docusaurus", // Usually your repo name.

  // Even if you don't use internalization, you can use this field to set useful
  // metadata like html lang. For example, if your site is Chinese, you may want
  // to replace "en" with "zh-Hans".
  i18n: {
    defaultLocale: "en",
    locales: ["en"],
  },

  presets: [
    [
      "classic",
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        docs: {
          sidebarPath: require.resolve("./sidebars.js"),
          // Please change this to your repo.
          // Remove this to remove the "edit this page" links.
          editUrl:
            "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/",
          docLayoutComponent: "@theme/DocPage",
          docItemComponent: "@theme/ApiItem", // Derived from docusaurus-theme-openapi-docs
        },
        blog: {
          showReadingTime: true,
          // Please change this to your repo.
          // Remove this to remove the "edit this page" links.
          editUrl:
            "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/",
        },
        theme: {
          customCss: require.resolve("./src/css/custom.css"),
        },
      }),
    ],
  ],
  plugins: [
    [
      "docusaurus-plugin-openapi-docs",
      {
        id: "openapi",
        config: {
          api: {
            // Note: petstore key is treated as the <id> and can be used to specify an API doc instance when using CLI commands
            specPath: "openapi/openapi.yaml", // Path to designated spec file
            outputDir: "api/openapi", // Output directory for generated .mdx docs
            sidebarOptions: {
              groupPathsBy: "tags",
            },
          },
        },
      },
    ],
    [
      "content-docs",
      {
        id: "openapi",
        path: "api",
        breadcrumbs: true,
        routeBasePath: "api",
        include: ["**/*.md", "**/*.mdx"],
        sidebarPath: "apiSidebars.js",
        docLayoutComponent: "@theme/DocPage", // This solves the providers issue and drop the need for ApiPage component
        docItemComponent: "@theme/ApiItem", // Will probably need to clean this up/refactor to get it fully updated
        remarkPlugins: [],
        rehypePlugins: [],
        beforeDefaultRemarkPlugins: [],
        beforeDefaultRehypePlugins: [],
        showLastUpdateAuthor: true, // We can now add stuff like this :)
        showLastUpdateTime: true,
      },
    ],
  ],
  themes: ["docusaurus-theme-openapi-docs"],
  themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    ({
      navbar: {
        title: "HailTrace",
        logo: {
          alt: "My Site Logo",
          src: "img/logo.svg",
        },
        items: [
          {
            to: "/api/openapi",
            position: "left",
            label: "OpenApi",
          },
          { to: "/blog", label: "Blog", position: "left" },
          {
            href: "https://github.com/facebook/docusaurus",
            label: "GitHub",
            position: "right",
          },
        ],
      },
      footer: {
        style: "dark",
        links: [
          {
            title: "Docs",
            items: [
              {
                label: "Tutorial",
                to: "/docs/intro",
              },
            ],
          },
          {
            title: "Community",
            items: [
              {
                label: "Stack Overflow",
                href: "https://stackoverflow.com/questions/tagged/hailtrace",
              },
              {
                label: "Twitter",
                href: "https://twitter.com/hailtrace",
              },
            ],
          },
          {
            title: "More",
            items: [
              {
                label: "Blog",
                to: "/blog",
              },
              {
                label: "GitHub",
                href: "https://github.com/hailtrace",
              },
            ],
          },
        ],
        copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,
      },
      prism: {
        theme: lightCodeTheme,
        darkTheme: darkCodeTheme,
      },
    }),
};

module.exports = config;

• Version used: 1.0.1 (plugin and theme)
• Environment name and version (e.g. Chrome 59, node.js 5.4, python 3.7.3): Chrome 100.0.4896.127
• Operating System and version (desktop or mobile): MacOS Monterey

[Bug] `resolveJsonRefs` not properly called/awaited

Describe the bug

The resolveJsonRefs function is not properly called, which sets the resolved variable value to a promise.

https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/main/packages/docusaurus-plugin-openapi-docs/src/openapi/utils/loadAndBundleSpec.ts#L66

Expected behavior

The function is async and should be preceded with the await keyword.

Current behavior

The function is not properly called.

Possible solution

Add the await keyword.

[FR] Support Parent Tag Grouping

Is your feature request related to a problem?

No

Describe the solution you'd like

Today, we can group by tag for multiple spec files within the same directory. It would be nice to have the ability to group a set of those spec files together in one parent category instead of having to define separate APIs in the config.

The idea:

Add a x-parent-category option to the spec file(s) that includes a Summary (display in the sidebar) . With that option, a sidebar category would be created and the items of that sidebar category would be a concatenation of the sidebar categories for each tag in each spec file that shares the x-parent-category.

A simplified example:

I have spec files for my shop named Apple, Banana, Double Shot, Latte, Cortado . In Apple, all endpoints are tagged Apple, in Banana all are tagged Banana, etc... I would create a x-parent-category: "Fruits" which would be added to the Apple and Banana spec files. The generated Sidebar would then have a top level category: Fruits with items that is an array of the Apple sidebar category and Banana sidebar category. The same thing would happen for x-parent-category of Espresso Drinks

We'd See on the sidebar:
Fruits ▼

Apple ▼

• buy apple
• clean apple
• eat apple

Banana ▼

• buy banana
• clean banana
• eat banana

Espresso Drinks ▼

Double Shot ▼

• buy double shot
• drink double shot

Double Shot ▼

• buy latte
• drink latte

Cortado ▼

• buy cortado
• drink cortado

The main difference between what is there today would be that if x-parent-category was specified the generated sidebar would add the higher level category. If no x-parent-category is specified, there would be no difference in the output.

Describe alternatives you've considered

Additional context

[Polish] Cleanup method color variables

Describe the bug

Currently there are gaps/inconsistencies in how --openapi-code-* colors map to --ifm-color-* colors. We are also missing a badge/color for the HEAD method in the ApiDemoPanel.

Expected behavior

We should strive to keep colors consistent between docusaurus-theme-openapi-docs and theme-classic.

Current behavior

Possible solution

Cleanup colors.

Steps to reproduce

Screenshots

Context

Your Environment

• Version used:
• Environment name and version (e.g. Chrome 59, node.js 5.4, python 3.7.3):
• Operating System and version (desktop or mobile):
• Link to your project:

[Bug] Can't enable circular `$ref` resolution

Describe the bug

Currently, circular $ref pointers are not fully resolved. The are explicitly "ignored" by the JSON schema dereference utility.

Expected behavior

Ideally, circular $ref pointers should be fully resolved, so long as serialization is not required or broken.

Current behavior

Some dependencies, like openapi-to-postman, are attempting to serialize the OpenAPI object which throws an error.

https://github.com/PaloAltoNetworks/openapi-to-postman/blob/develop/lib/common/versionUtils.js#L93

https://github.com/PaloAltoNetworks/openapi-to-postman

Possible solution

Refactor openapi-to-postman to no longer require serializing the OpenAPI object prior to converting into a postman collection. Additionally, locate and refactor any other such instances.

Ultimately, the goal would be to fully dereference and preserve circular $ref pointers as an object.

[FR] Add support for client credentials security scheme

Is your feature request related to a problem?

Requesting support for client credentials security scheme. Could also include support for remaining security scheme types.

Describe the solution you'd like

A solution similar to our support for API keys and basic auth.

Describe alternatives you've considered

N/A

Additional context

Since we are no longer allowing users to enter their credentials it may also be a good time to cleanup the Redux slice and Authorize button and any other unused code.

Module not found: Error: Can't resolve '@theme/DocItemFooter'

Describe the bug

I'm using Docusaurus 2.0.0-rc.1 and getting this error:

Module not found: Error: Can't resolve '@theme/DocItemFooter' in node_modules/docusaurus-theme-openapi-docs/lib-next/theme/ApiItem'.

My plugin section looks like this:

      '@docusaurus/plugin-content-docs',
      {
        path: 'docs/api/petstore',
        routeBasePath: '/api/petstore',
        id: 'apiPetstore',
        sidebarPath: require.resolve('./sidebars/petstore.js'),
        sidebarCollapsible: false,
        docLayoutComponent: "@theme/DocPage",
        docItemComponent: "@theme/ApiItem",
      },
    ],

Thanks!

[Bug] Docusaurus server-side rendering could not render static page with path ReactContextError

Describe the bug

Running npm run build returns a lot of:

[ERROR] Docusaurus server-side rendering could not render static page with path /api/petstore/category/...
ReactContextError

Expected behavior

It should build a static website.

Current behavior

[ERROR] Unable to build website for locale en.
[ERROR] Error: Failed to compile with errors.
    at /Home/common/temp/node_modules/.pnpm/@[email protected]_818345a8d7cf6af82aae687b15f8b782/node_modules/@docusaurus/core/lib/webpack/utils.js:180:24
    at /Home/common/temp/node_modules/.pnpm/[email protected]/node_modules/webpack/lib/MultiCompiler.js:554:14
    at processQueueWorker (/Home/common/temp/node_modules/.pnpm/[email protected]/node_modules/webpack/lib/MultiCompiler.js:491:6)
    at processTicksAndRejections (node:internal/process/task_queues:78:11)

Your Environment

Docusaurus: 2.0.0-rc.1
OpenAPI-docs: 1.1.1

Using pnpm and rush.

Part of docusaurus.config:

    [
      'docusaurus-plugin-openapi-docs',
      {
        id: 'petstore',
        docsPluginId: 'apiPetstore',
        config: {
          petstore: { // Note: petstore key is treated as the <id> and can be used to specify an API doc instance when using CLI commands
            specPath: 'static/api/v1.yaml', // Path to designated spec file
            outputDir: 'docs/api/petstore', // Output directory for generated .mdx docs
            sidebarOptions: {
              groupPathsBy: 'tag',
              sidebarCollapsible: true,
              sidebarCollapsed: true,
            },
          },
        }
      },
    ],

    [
      '@docusaurus/plugin-content-docs',
      {
        path: 'docs/api/petstore',
        routeBasePath: '/api/petstore',
        id: 'apiPetstore',
        sidebarPath: require.resolve('./sidebars/petstore.js'),
        sidebarCollapsible: false,
        docLayoutComponent: '@theme/DocPage',
        docItemComponent: '@theme/ApiItem',
      },
    ],

plugins.js

const { ProvidePlugin } = require('webpack');
const path = require('path');

const tailwindPlugin = (context, options) => {
  return {
    name: 'tailwind-plugin',
    configurePostCss(postcssOptions) {
      postcssOptions.plugins = [
        require('postcss-import'),
        require('tailwindcss/nesting'),
        require('tailwindcss'),
        require('autoprefixer'),
      ];
      return postcssOptions;
    },
  };
};

const webpackPlugin = (context, options) => {
  return {
    name: 'webpack-plugin',
    configureWebpack(config) {
      return {
        module: {
          rules: [
            {
              test: /\.m?js/,
              resolve: {
                fullySpecified: false,
              },
            },
          ],
        },
        plugins: [
          new ProvidePlugin({
            process: require.resolve('process/browser'),
          }),
        ],
        resolve: {
          fallback: {
          },
          alias: {
          },
        },
      };
    },
  };
};


module.exports = { tailwindPlugin, webpackPlugin };

Is there any way to get more debug information than just ReactContextError?

Is there a way to upload yaml file and render UI on live?

[FR] Expand details by 1L for desktop view

Is your feature request related to a problem?

Not really, more of an enhancement.

Describe the solution you'd like

Might be useful to expand details components by one level for desktop view. Mobile can stay collapsed by default.

Describe alternatives you've considered

I've tried expanding the details myself but it adds at least one extra click and sometimes I'm disappointed with what I see.

Additional context

This is more of a UI/UX enhancement request, so I expect there might be some discussion around whether it makes sense.

I believe Docusaurus has a useWindowSize() hook included but I'm not sure it makes sense to use in this scenario, since it's intended for React components.

[Bug] Paginator not rendering on history change

Describe the bug

Paginator is sometimes not rendering when cycling through endpoints via the sidebar. It seems to always appear on initial page load but not on history change.

Expected behavior

Paginator should appear for every API doc, regardless of how a user navigates to it.

Current behavior

Screen.Recording.2022-04-28.at.9.20.33.AM.mov

Possible solution

Investigate this block of code: https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/panw-main/packages/docusaurus-theme-openapi/src/theme/ApiItem/index.tsx#L35

Steps to reproduce

Replicate using https://docusaurus-openapi.tryingpan.dev/

Screenshots

Context

Your Environment

• Version used:
• Environment name and version (e.g. Chrome 59, node.js 5.4, python 3.7.3):
• Operating System and version (desktop or mobile):
• Link to your project:

[FR] Improve overall error handling and fault tolerance

Is your feature request related to a problem?

Under most circumstances, the docusaurus-plugin-openapi-docs plugin successfully reads, parses and generates MDX for a given OpenAPI specification. Still, there are times when processing errors occur, due to gaps or incompatibilities, which can lead to exceptions. These errors can occur for a number of reasons at a number of points during processing, including:

• Conversion of OAS to postman collection
• Creation of API items (especially when creating sample request payloads/schemas)

Describe the solution you'd like

• Better, more informative errors/traces, i.e. include function, spec path, etc.
• Better fault tolerance, i.e. continue processing other specs after failure
• Pre-flight validation checks before proceeding with deeper processing

Describe alternatives you've considered

Focusing more on validating the OAS outside of the plugin using various linters, extensions, tools, etc.

Additional context

Improvements in this area would greatly enhance the usability of the plugin while also decreasing the time needed to diagnose failures and deliver fixes.

TODO

• Document process flow (diagram?) and where failures could occur
• Implement pre-flight validation to help fail faster
• Add appropriate exception handling to functions prone to failure
• Pass/add appropriate context to improve error messages
• Support continue on failure/error
• Improve logging, i.e. provide more logging to understand where we are in the process

Smaller Fixes

• PAN-OS REST API [ERROR] TypeError: Cannot read properties of undefined (reading 'default')

Incompatible with Beta22

Describe the bug

Due to the changes to DocItem this is no longer compatible with Docusaurus Beta22

Expected behavior

Plugin works

Current behavior

Plugin errors because DocItemFooter no longer exists.

Possible solution

Steps to reproduce

Install Beta22 and attempt to build or serve.

[FR] Support for Response Headers

Is your feature request related to a problem?

Currently, there is no support for Response Headers. Potential solution would be to follow suit with Redoc, where the Response Headers renders above the Response Schema. See example below:

Describe the solution you'd like

Describe alternatives you've considered

Additional context

[FR] Include status code response examples when available

Is your feature request related to a problem?

Currently we do nothing with response examples, which could be helpful for understanding possible responses the API could return for different status codes.

Describe the solution you'd like

In addition to response code Schema, we can provide the end user with the option to select and view example responses for that status code, similar to how ReDoc handles it.

ReDoc example:

Screen.Recording.2022-06-03.at.5.46.22.PM.mov

Describe alternatives you've considered

Not including examples, although I think they could be helpful to users.

Additional context

Each status code response will have its own set of examples. Whatever we come up with should provide the ability to select which example to display.

🗑️ 🦝 [Spring Cleaning] Rename packages and update documentation

Description

This issue is for tracking progression through renaming repository and packages and updating all supporting licenses and docs, e.g. READMEs, license headers, usage, screenshots, etc.

Proposed naming:

Repository: docusaurus-openapi-docs
Plugin: docusaurus-plugin-openapi-docs
Theme: docusaurus-theme-openapi-docs

Logo: TBD

Motivation

Since forking the original docusaurus-openapi we have diverged enough to warrant breaking the fork and spinning off our own project. With that said, we'd like to remain friendly to the rest of the Docusaurus community by packaging and offering our version of the plugin such that other Docusaurus users may potentially use it in their projects.

TODO

• Update README.md (screenshots, badges and usage) #64
• Update LICENSE (and .eslintrc.js rules) (adopt panw license) #64
• Update CONTRIBUTING.md #65
• Add SUPPORT.md (adopt panw community support) #65
• Update CODE_OF_CONDUCT.md (adopt panw if appropriate) #65
• Update docusaurus-plugin-openapi README.md (screenshots and usage) #68
• Rename packages, i.e. remove @paloaltonetworks/ scope and rename folders and package.json "name" #69
• Rename repository and update topics, descriptions, etc. (GitHub will auto-redirect old to new)
• Final scrub/cleanup
• Publish new packages to npmjs #73

[Bug] Console warning: Duplicate key for multiple Security Schemes

Describe the bug

In some cases, certain API's require multiple security schemes for authentication. As of now, the current <SecuritySchemes /> component only supports a single security scheme render.

Expected behavior

There should be unique keys for each security scheme element to rid of any React warnings in the console. In addition, the "Authorization:" title is repeated for each Security Scheme and should be refactored and restyled to only render once.

Current behavior

React related console warnings for duplicate keys and repeated "Authorization: " title.

Possible solution

Handling the duplicate keys should be straight-forward. As for the repeated "Authorization: " title, the <SecuritySchemes /> component can be refactored in a manner that renders a list and a single "Authorization: " title (for API's that require multiple security schemes)

Steps to reproduce

1. Generate docs with IoT API
2. Navigate to any IoT API doc page
3. Observe console warnings
4. Observe duplicate "Authorization: " title

Screenshots

Context

Your Environment

• Version used:
• Environment name and version (e.g. Chrome 59, node.js 5.4, python 3.7.3):
• Operating System and version (desktop or mobile):
• Link to your project:

[Bug] Circular label not being applied in all cases

Describe the bug

With the new resolver/serializer, circular schema references should be replaced with a "circular" label. There are cases where this label is not properly applied (see below):

Expected behavior

Circular label should appear next to the property with the circular reference:

Possible solution

• Debug createSchemaDetails to determine if and where the label may be getting dropped/lost.
• Debug the serializer function to determine if label is left out in some cases

Steps to reproduce

See #154 deploy preview

Question: Can we add additional code samples?

This seems not to read the x-codesample from the API spec but is instead generating it's own code examples. So can we hook into that to add, for example, PowerShell examples?

[FR] Execute query from docs page

Is your feature request related to a problem?

No way to execute queries from docs page right now since Execute button has been removed.

Noticed that Execute button for executing queries directly from the docs page used to be there but was removed from v18.0.0 onwards.

Describe the solution you'd like

Bring back the query execution capability.

Describe alternatives you've considered

Right now I'm falling back to another older plugin of yours https://github.com/cloud-annotations/docusaurus-openapi
But this project's approach of generating mdx docs from Swagger is much more flexible since I can easily add additional md files for supplementary information and I'd like to switch to this. But the removal of the feature makes it a very difficult sell since my boss explicitly wants it :(

Additional context

Users benefit greatly from being able to run queries from docs page rather than have to download Postman or use curl

[FR] Improve multi/micro-spec support

Is your feature request related to a problem?

Currently, docs produced from multiple specs are written to the same directory and directory level. This presents issue when organizing and/or constructing sidebars for different APIs.

Describe the solution you'd like

An organization strategy for handling multi-specs. For example:

• Group and write MDX files to a subdirectory named after kebab-cased info.title
• Continue to write all MDX files to same directory but generate unique *.sidebar.js slices for each API
• Introduce groupPathsBy: 'file' to sidebarOptions

Describe alternatives you've considered

Manually constructing the sidebar object can be a painful experience for medium to large APIs.

Additional context

• We should maintain cross-compatibility with Docusaurus sidebars features like autogenerated and __category__.json
• If generating a single sidebar.js for multiple APIs, each API should be grouped by category label. We would need to decide what label to use or where to derive it from, e.g. kebab-cased info.title?
• Micro-specs are different, since they represent a single, logical API. For those, we'd ideally just group by 'tag'

[Bug] Servers form component no longer appearing above code samples

Describe the bug

Since #160 we are missing the Servers component used for selecting the base URL for code samples.

Expected behavior

Servers component should normally appear above code samples section.

Current behavior

It's no longer visible.

[Theme] Possible @theme/Tabs namespace collision

Describe the bug

The Tabs component included in docusaurus-theme-openapi-docs directly conflicts with the one included in docusaurus-theme-classic.

Expected behavior

The components in docusaurus-theme-openapi-docs should not affect components from other themes.

Current behavior

@theme/Tabs namespace collision

Possible solution

Consider renaming docusaurus-theme-openapi-docs components in order to avoid potential namespace collisions with other themes. In this particular case, perhaps something like ResponseTabs would suffice. Alternatively we could roll with something like ApiTabs.

Screenshot

Tabs above should render like this: https://cortex.pan.dev/docs/data_lake/learn/about_cdl#region-base-urls

[FR] Extend Docusaurus syntax highlighting to code samples

Is your feature request related to a problem?

Today, syntax highlighting for API code samples is distinct from the syntax highlighting applied by Docusaurus.

Describe the solution you'd like

Ideally, the syntax highlighting configured in docusaurus.config.js would automatically be applied to the code samples (and possibly the live request payload/param editor).

Describe alternatives you've considered

Attempting to use CSS variables to match the style, which doesn't always work well.

Additional context

One possible solution might be to adapt the Curl theme component to use the built-in Docusaurus CodeBlock component. I am not sure how we'd match styles with Monaco/VSCode editor, but it's possible we could pass the Docusaurus styles with prism-react-renderer.

Error when generating sidebars.

Describe the bug

Cannot generate site - sidebar file generating incorrect document IDs for category/tag pages.

Expected behavior

yarn build should complete successfully.

Current behavior

The following error is seen:

Possible solution

Manually correcting the paths in the output directory's sidebar.js file fixed the issue until the docs are regenerated.

Steps to reproduce

1. Using this API definition: https://gist.github.com/homotechsual/e32d9c815c62b41501dc7d049fbd06f5
2. Config: https://gist.github.com/homotechsual/a8b7cc5f405ad97e51ed988c87426454

Context

Documenting moderately complex REST APIs using json schemas.

[FR] Generate tags as doc pages with embedded index

Is your feature request related to a problem?

There are no plans to introduce markdown/MDX support to generated-index link descriptions. Many of our API specs contain markdown in their tag descriptions which leads to broken or unreadable text.

Describe the solution you'd like

Allow support for generating tag doc pages with embedded index when categoryLinkSource is set to "tag". This would also change the sidebar category link config type from generated-index to doc.

Describe alternatives you've considered

Considered opening a FR but Docusaurus maintainers explained that markdown link descriptions cannot be supported since they also double as meta description.

Additional context

May need to come up with a naming convention for "tag docs", similar to info docs. Perhaps kebab-case the tag name?

[FR] Support for downloading OpenAPI specification file

Is your feature request related to a problem?

Today, there is no method for downloading the source OpenAPI specification file, for use "offline", e.g. Postman, Insomnia, SDK generation, some other doc tool, etc.

Describe the solution you'd like

Ability to download a formatted, enriched copy of the OpenAPI spec for each set of API docs.

Describe alternatives you've considered

Linking to GitHub?

Additional context

Single spec and multi should be "easy" since we can potentially just read them in, convert to postman collection, then back to OAS yaml file. Micro-specs could be a challenge since each spec is a part of the whole.

[FR] Add support for displaying property default values

Is your feature request related to a problem?

Currently we do not support displaying default values.

Describe the solution you'd like

Add support for displaying default values when available, similar to ReDoc:

(Notice the "Default: 1" that is displayed under the property type and qualifier.)

Describe alternatives you've considered

n/a

Additional context

n/a

[FR] Write remaining info fields to index.api.mdx

Is your feature request related to a problem?

Currently, we include only the info title, description and version badge.

Describe the solution you'd like

Ideally, we would also include any remaining fields, e.g. support contact, support URL, terms of service, license. See the following for more details: https://swagger.io/docs/specification/api-general-info/

Describe alternatives you've considered

N/A

Additional context

Feel free to format as needed for optimal display.

[Community Health Assessment] Changes needed

This issue was opened by a bot called Community Health (PANW) because this repo has failed too many community health checks.

Repo maintainers: Please take the time to fix the issues in the table to reach the target score. These improvements will help others find your work and contribute to it. This issue will update as your score improves until it hits the target score.

Click More info for instructions to fix each item.

Health Check	Pass	Score	More Info
Contains a meaningful README.md file	✅	20 / 20	More info
SUPPORT.md file exists	✅	20 / 20	More info
Repo has a description	✅	15 / 15	More info
Has a recognized open source license	✅	15 / 15	More info
Has a descriptive repo name	✅	15 / 15	More info
Required topics attached to repo	❌	0 / 15	More info
CONTRIBUTING.md file with contribution guidelines	✅	5 / 5	More info
Has custom issue and pull request templates	❌	0 / 5	More info

Current score: 90
Target threshold: 100
Total possible: 110

[FR] Ability to sync language choice

Is your feature request related to a problem?

When navigating from one API doc to another the selected language does not persist.

Describe the solution you'd like

Ability to sync and persist the language choice across all API docs. For example, if a user chooses "Python" then the choice should be persisted locally and automatically selected when they move across API docs.

Describe alternatives you've considered

N/A

Additional context

Ideally, I think we'd want to implement Docusaurus Tab synching but it might require refactoring language buttons into tabs.

https://docusaurus.io/docs/markdown-features/tabs#syncing-tab-choices