feat: Implement authPersistence in ThemeConfig

[tayles]

Description

Implements authPersistence option for ThemeConfig, to allow disabling of sessionStorage persistence.

• Defaults to sessionStorage (current behavior)
• Set to false to disable storage

Motivation and Context

Resolves #1239

Also provides a workaround to resolve #1238

An authPersistence configuration option is mentioned in the v0.2.1 (Dec 5, 2021) changelog (https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/main/CHANGELOG.md#021-dec-5-2021), and the configuration types are already in place, but it is not currently implemented in the latest version.

How Has This Been Tested?

Add authPersistence: false to docusaurus.config.ts:

import type { Config } from '@docusaurus/types';
import type * as Preset from '@docusaurus/preset-classic';
import type * as OpenApiPlugin from 'docusaurus-plugin-openapi-docs';
import type { ThemeConfig as OpenApiThemeConfig } from 'docusaurus-theme-openapi-docs';

const config: Config = {
  ...
  themeConfig: {
    api: {
      authPersistence: false,
    },
  } satisfies Preset.ThemeConfig & OpenApiThemeConfig,
};
export default config;

• Entering security scheme details in the request panel e.g. https://docusaurus-openapi.tryingpan.dev/petstore/add-pet
• Ensure that browser sessionStorage is not updated

As a side effect, persistence of server variables will also be disabled by settings this to false, as this uses the same persistence middleware.

NOTE: The current types in https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/main/packages/docusaurus-theme-openapi-docs/src/types.ts have a slight spelling mistake: authPersistance. This has been renamed to authPersistence.

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.

[github-actions]

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

https://docusaurus-openapi-36b86--pr1240-zj7362xc.web.app

_{(expires Thu, 11 Dec 2025 15:08:25 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

_{Sign: bf293780ee827f578864d92193b8c2866acd459f}

[sserrata]

Hi @tayles, thanks for the PR! Please find my review and suggestions below:

Critical

• File: packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/persistanceMiddleware.ts:65-67

  • Issue: Non-null assertion operator (JSON.parse(server!)) is unsafe when storage.getItem("server") returns null
  • Fix: Add null check before parsing:

    const server = storage.getItem("server");
    if (!server) {
      return result;
    }
    const variables = JSON.parse(action.payload);
    let serverObject = JSON.parse(server) as ServerObject;

• File: packages/docusaurus-theme-openapi-docs/src/theme/ApiItem/index.tsx:138

  • Issue: Non-null assertion operator (JSON.parse(server!)) creates runtime risk when storage.getItem("server") returns null
  • Fix: Add proper null handling:

    const server = storage.getItem("server");
    const serverObject = server ? (JSON.parse(server) as ServerObject) : {};

Minor (this one is optional since the type already existed before your PR)

• File: packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/persistanceMiddleware.ts:1 (filename)

  • Issue: The filename contains the misspelling "persistanceMiddleware" (should be "persistenceMiddleware") which is inconsistent with the corrected API naming
  • Fix: Rename file to persistenceMiddleware.ts and update all imports across the codebase

• File: packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/storage-utils.ts:20

  • Issue: Type name Persistance contains spelling error (should be Persistence), creating inconsistency with the corrected ThemeConfig option
  • Fix: Rename type to Persistence and update the createStorage function signature

Minor (optional but appreciated)

• File: packages/docusaurus-theme-openapi-docs/src/types.ts:14

  • Issue: Missing JSDoc comment explaining the authPersistence configuration option and its behavior
  • Fix: Add documentation:

    /**
     * Controls how authentication credentials are persisted in the API explorer.
     * - `false`: No persistence (in-memory only)
     * - `"sessionStorage"`: Persist for the browser session (default)
     * - `"localStorage"`: Persist across browser sessions
     */
    authPersistence?: false | "localStorage" | "sessionStorage";

• File: packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/persistanceMiddleware.ts:13-14

  • Issue: Import order mixes plugin and theme imports; type imports should use consistent style
  • Fix: Group imports by package and use consistent type import syntax:

    import type { ServerObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
    import type { ThemeConfig } from "docusaurus-theme-openapi-docs/src/types";

[tayles]

Thanks @sserrata for your review, I have addressed these issues apart from your last point:

• File: packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/persistanceMiddleware.ts:13-14

  • Issue: Import order mixes plugin and theme imports; type imports should use consistent style
  • Fix: Group imports by package and use consistent type import syntax:

    import type { ServerObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
    import type { ThemeConfig } from "docusaurus-theme-openapi-docs/src/types";

I didn't quite understand what you mean by this sorry. I think the imports are already correctly sorted and accurate? I updated some of the other unrelated type-only imports in this file in
3e04310, in case that is what you are referring to.

There were 2 other things I wanted to ask:

1. I don't believe the proxy config option in https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/main/packages/docusaurus-theme-openapi-docs/src/types.ts#L13 is read anywhere (I think it has moved under per-schema APIOptions instead) - would you like me to remove this for clarity?
2. Would you like me to document this config option in the readme?