[V3] Refactor theme package to Typescript (#684)

* TypeScript refactor ApiCodeBlock * TypeScript refactor Tabs * TypeScript refactor components * Add inline code to clean method * TypeScript refactor items * Test ClientWidth arrows, update flatten TabChildren * Lint fixes * Fix Sidebar prettier and typing issues * Fix greedy curly bracket escape
PaloAltoNetworks · Jan 5, 2024 · 677381d · 677381d
1 parent 4836267
commit 677381d
Show file tree

Hide file tree

Showing 53 changed files with 3,988 additions and 5,293 deletions.
diff --git a/demo/docusaurus.config.ts b/demo/docusaurus.config.ts
@@ -133,7 +133,15 @@ const config: Config = {
       copyright: `Copyright © ${new Date().getFullYear()} Palo Alto Networks, Inc. Built with Docusaurus ${DOCUSAURUS_VERSION}.`,
     },
     prism: {
-      additionalLanguages: ["ruby", "csharp", "php", "java", "powershell"],
+      additionalLanguages: [
+        "ruby",
+        "csharp",
+        "php",
+        "java",
+        "powershell",
+        "json",
+        "bash",
+      ],
     },
     languageTabs: [
       {

diff --git a/demo/package.json b/demo/package.json
@@ -27,7 +27,7 @@
     "clsx": "^1.1.1",
     "docusaurus-plugin-openapi-docs": "^3.0.0-beta.3",
     "docusaurus-theme-openapi-docs": "^3.0.0-beta.3",
-    "prism-react-renderer": "^2.1.0",
+    "prism-react-renderer": "^2.3.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
   },

diff --git a/packages/docusaurus-plugin-openapi-docs/package.json b/packages/docusaurus-plugin-openapi-docs/package.json
@@ -49,6 +49,7 @@
     "fs-extra": "^9.0.1",
     "json-pointer": "^0.6.2",
     "json-schema-merge-allof": "^0.8.1",
+    "json5": "^2.2.3",
     "lodash": "^4.17.20",
     "mustache": "^4.2.0",
     "slugify": "^1.6.5",

diff --git a/packages/docusaurus-plugin-openapi-docs/src/index.ts b/packages/docusaurus-plugin-openapi-docs/src/index.ts
@@ -12,6 +12,7 @@ import zlib from "zlib";
 import type { LoadContext, Plugin } from "@docusaurus/types";
 import { Globby, posixPath } from "@docusaurus/utils";
 import chalk from "chalk";
+import JSON5 from "json5";
 import { render } from "mustache";
 
 import { createApiPageMD, createInfoPageMD, createTagPageMD } from "./markdown";
@@ -144,12 +145,15 @@ export default function pluginOpenAPIDocs(
           docPath
         );
 
-        let sidebarSliceTemplate = `import {SidebarConfig} from "@docusaurus/plugin-content-docs/src/sidebars/types";\n\n`;
-        sidebarSliceTemplate += `const sidebar: SidebarConfig = {{{slice}}};\n\n`;
-        sidebarSliceTemplate += `export default sidebar;`;
+        let sidebarSliceTemplate = `import type { SidebarsConfig } from "@docusaurus/plugin-content-docs";\n\n`;
+        sidebarSliceTemplate += `const sidebar: SidebarsConfig = {{{slice}}};\n\n`;
+        sidebarSliceTemplate += `export default sidebar.apisidebar;\n`;
 
         const view = render(sidebarSliceTemplate, {
-          slice: JSON.stringify(sidebarSlice, null, 2),
+          slice: JSON5.stringify(
+            { apisidebar: sidebarSlice },
+            { space: 2, quote: '"' }
+          ),
         });
 
         if (!fs.existsSync(`${outputDir}/sidebar.ts`)) {
@@ -427,7 +431,11 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
 
     const versionsJson = JSON.stringify(versionsArray, null, 2);
     try {
-      fs.writeFileSync(`${outputDir}/versions.json`, versionsJson, "utf8");
+      fs.writeFileSync(
+        `${outputDir}/versions.json`,
+        versionsJson + "\n",
+        "utf8"
+      );
       console.log(
         chalk.green(`Successfully created "${outputDir}/versions.json"`)
       );

diff --git a/packages/docusaurus-plugin-openapi-docs/src/markdown/createAuthentication.ts b/packages/docusaurus-plugin-openapi-docs/src/markdown/createAuthentication.ts
@@ -5,9 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { OAuthFlowObject, SecuritySchemeObject } from "../openapi/types";
 import { createDescription } from "./createDescription";
 import { create, guard } from "./utils";
+import { OAuthFlowObject, SecuritySchemeObject } from "../openapi/types";
 
 export function createAuthentication(securitySchemes: SecuritySchemeObject) {
   if (!securitySchemes || !Object.keys(securitySchemes).length) return "";

diff --git a/packages/docusaurus-plugin-openapi-docs/src/markdown/createContactInfo.ts b/packages/docusaurus-plugin-openapi-docs/src/markdown/createContactInfo.ts
@@ -5,8 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { ContactObject } from "../openapi/types";
 import { create, guard } from "./utils";
+import { ContactObject } from "../openapi/types";
 
 export function createContactInfo(contact: ContactObject) {
   if (!contact || !Object.keys(contact).length) return "";

diff --git a/packages/docusaurus-plugin-openapi-docs/src/markdown/createLicense.ts b/packages/docusaurus-plugin-openapi-docs/src/markdown/createLicense.ts
@@ -5,8 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { LicenseObject } from "../openapi/types";
 import { create, guard } from "./utils";
+import { LicenseObject } from "../openapi/types";
 
 export function createLicense(license: LicenseObject) {
   if (!license || !Object.keys(license).length) return "";

diff --git a/packages/docusaurus-plugin-openapi-docs/src/markdown/createLogo.ts b/packages/docusaurus-plugin-openapi-docs/src/markdown/createLogo.ts
@@ -5,8 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { LogoObject } from "../openapi/types";
 import { create, guard } from "./utils";
+import { LogoObject } from "../openapi/types";
 
 export function createLogo(
   logo: LogoObject | undefined,

diff --git a/packages/docusaurus-plugin-openapi-docs/src/markdown/createParamsDetails.ts b/packages/docusaurus-plugin-openapi-docs/src/markdown/createParamsDetails.ts
@@ -5,10 +5,10 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { ApiItem } from "../types";
 import { createDetails } from "./createDetails";
 import { createDetailsSummary } from "./createDetailsSummary";
 import { create } from "./utils";
+import { ApiItem } from "../types";
 
 interface Props {
   parameters: ApiItem["parameters"];

diff --git a/packages/docusaurus-plugin-openapi-docs/src/markdown/createRequestBodyDetails.ts b/packages/docusaurus-plugin-openapi-docs/src/markdown/createRequestBodyDetails.ts
@@ -5,8 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { MediaTypeObject } from "../openapi/types";
 import { createRequestSchema } from "./createRequestSchema";
+import { MediaTypeObject } from "../openapi/types";
 
 interface Props {
   title: string;

diff --git a/packages/docusaurus-plugin-openapi-docs/src/markdown/createRequestSchema.ts b/packages/docusaurus-plugin-openapi-docs/src/markdown/createRequestSchema.ts
@@ -5,12 +5,12 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { MediaTypeObject } from "../openapi/types";
 import { createDescription } from "./createDescription";
 import { createDetails } from "./createDetails";
 import { createDetailsSummary } from "./createDetailsSummary";
 import { createNodes } from "./createSchema";
 import { create, guard } from "./utils";
+import { MediaTypeObject } from "../openapi/types";
 
 interface Props {
   style?: any;

diff --git a/packages/docusaurus-plugin-openapi-docs/src/markdown/createResponseSchema.ts b/packages/docusaurus-plugin-openapi-docs/src/markdown/createResponseSchema.ts
@@ -5,7 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { MediaTypeObject } from "../openapi/types";
 import { createDescription } from "./createDescription";
 import { createDetails } from "./createDetails";
 import { createDetailsSummary } from "./createDetailsSummary";
@@ -16,6 +15,7 @@ import {
   createResponseExamples,
 } from "./createStatusCodes";
 import { create, guard } from "./utils";
+import { MediaTypeObject } from "../openapi/types";
 
 interface Props {
   style?: any;

diff --git a/packages/docusaurus-plugin-openapi-docs/src/markdown/createSchema.test.ts b/packages/docusaurus-plugin-openapi-docs/src/markdown/createSchema.test.ts
@@ -7,8 +7,8 @@
 
 import * as prettier from "prettier";
 
-import { SchemaObject } from "../openapi/types";
 import { createNodes } from "./createSchema";
+import { SchemaObject } from "../openapi/types";
 
 describe("createNodes", () => {
   it("should create readable MODs for oneOf primitive properties", async () => {

diff --git a/packages/docusaurus-plugin-openapi-docs/src/markdown/createSchema.ts b/packages/docusaurus-plugin-openapi-docs/src/markdown/createSchema.ts
@@ -7,7 +7,6 @@
 
 import clsx from "clsx";
 
-import { SchemaObject } from "../openapi/types";
 import {
   createClosingArrayBracket,
   createOpeningArrayBracket,
@@ -17,6 +16,7 @@ import { createDetails } from "./createDetails";
 import { createDetailsSummary } from "./createDetailsSummary";
 import { getQualifierMessage, getSchemaName } from "./schema";
 import { create, guard } from "./utils";
+import { SchemaObject } from "../openapi/types";
 
 const jsonSchemaMergeAllOf = require("json-schema-merge-allof");
 

diff --git a/packages/docusaurus-plugin-openapi-docs/src/markdown/createStatusCodes.ts b/packages/docusaurus-plugin-openapi-docs/src/markdown/createStatusCodes.ts
@@ -7,14 +7,14 @@
 
 import format from "xml-formatter";
 
-import { sampleResponseFromSchema } from "../openapi/createResponseExample";
-import { ApiItem } from "../types";
 import { createDescription } from "./createDescription";
 import { createDetails } from "./createDetails";
 import { createDetailsSummary } from "./createDetailsSummary";
 import { createResponseSchema } from "./createResponseSchema";
 import { create } from "./utils";
 import { guard } from "./utils";
+import { sampleResponseFromSchema } from "../openapi/createResponseExample";
+import { ApiItem } from "../types";
 
 export default function json2xml(o: any, tab: any) {
   var toXml = function (v: any, name: string, ind: any) {

diff --git a/packages/docusaurus-plugin-openapi-docs/src/markdown/index.ts b/packages/docusaurus-plugin-openapi-docs/src/markdown/index.ts
@@ -5,13 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import {
-  ContactObject,
-  LicenseObject,
-  MediaTypeObject,
-  SecuritySchemeObject,
-} from "../openapi/types";
-import { ApiPageMetadata, InfoPageMetadata, TagPageMetadata } from "../types";
 import { createAuthentication } from "./createAuthentication";
 import { createAuthorization } from "./createAuthorization";
 import { createContactInfo } from "./createContactInfo";
@@ -30,6 +23,13 @@ import { createTermsOfService } from "./createTermsOfService";
 import { createVendorExtensions } from "./createVendorExtensions";
 import { createVersionBadge } from "./createVersionBadge";
 import { render } from "./utils";
+import {
+  ContactObject,
+  LicenseObject,
+  MediaTypeObject,
+  SecuritySchemeObject,
+} from "../openapi/types";
+import { ApiPageMetadata, InfoPageMetadata, TagPageMetadata } from "../types";
 
 interface Props {
   title: string;

diff --git a/packages/docusaurus-plugin-openapi-docs/src/markdown/utils.ts b/packages/docusaurus-plugin-openapi-docs/src/markdown/utils.ts
@@ -50,8 +50,8 @@ export const lessThan =
 export const greaterThan =
   /(?<!(button|code|details|summary|hr|br|span|strong|small|table|thead|tbody|td|tr|th|h1|h2|h3|h4|h5|h6|title|p|em|b|i|u|strike|bold|a|li|ol|ul|img|svg|div|center|\/|\s|"|'))>/gu;
 export const codeFence = /`{1,3}[\s\S]*?`{1,3}/g;
-export const curlyBrackets = /\{(.*)}/g;
-export const codeBlock = /^(```.*[\s\S]*?```)$/gm;
+export const curlyBrackets = /([{|}])/g;
+export const codeBlock = /(^```.*[\s\S]*?```$|`[^`].+?`)/gm;
 
 export function clean(value: string | undefined): string {
   if (!value) {
@@ -60,14 +60,14 @@ export function clean(value: string | undefined): string {
 
   let sections = value.split(codeBlock);
   for (let sectionIndex in sections) {
-    if (!sections[sectionIndex].startsWith("```")) {
+    if (!sections[sectionIndex].startsWith("`")) {
       sections[sectionIndex] = sections[sectionIndex]
         .replace(lessThan, "&lt;")
         .replace(greaterThan, "&gt;")
         .replace(codeFence, function (match) {
           return match.replace(/\\>/g, ">");
         })
-        .replace(curlyBrackets, "\\{$1\\}");
+        .replace(curlyBrackets, "\\$1");
     }
   }
   return sections.join("");

diff --git a/packages/docusaurus-plugin-openapi-docs/src/openapi/createRequestExample.ts b/packages/docusaurus-plugin-openapi-docs/src/openapi/createRequestExample.ts
@@ -8,8 +8,8 @@
 import chalk from "chalk";
 import merge from "lodash/merge";
 
-import { mergeAllOf } from "../markdown/createSchema";
 import { SchemaObject } from "./types";
+import { mergeAllOf } from "../markdown/createSchema";
 
 interface OASTypeToTypeMap {
   string: string;

diff --git a/packages/docusaurus-plugin-openapi-docs/src/openapi/createResponseExample.ts b/packages/docusaurus-plugin-openapi-docs/src/openapi/createResponseExample.ts
@@ -8,8 +8,8 @@
 import chalk from "chalk";
 import merge from "lodash/merge";
 
-import { mergeAllOf } from "../markdown/createSchema";
 import { SchemaObject } from "./types";
+import { mergeAllOf } from "../markdown/createSchema";
 
 interface OASTypeToTypeMap {
   string: string;

diff --git a/packages/docusaurus-plugin-openapi-docs/src/openapi/openapi.ts b/packages/docusaurus-plugin-openapi-docs/src/openapi/openapi.ts
@@ -18,6 +18,9 @@ import kebabCase from "lodash/kebabCase";
 import unionBy from "lodash/unionBy";
 import uniq from "lodash/uniq";
 
+import { sampleRequestFromSchema } from "./createRequestExample";
+import { OpenApiObject, TagObject } from "./types";
+import { loadAndResolveSpec } from "./utils/loadAndResolveSpec";
 import { isURL } from "../index";
 import {
   ApiMetadata,
@@ -27,9 +30,6 @@ import {
   SidebarOptions,
   TagPageMetadata,
 } from "../types";
-import { sampleRequestFromSchema } from "./createRequestExample";
-import { OpenApiObject, TagObject } from "./types";
-import { loadAndResolveSpec } from "./utils/loadAndResolveSpec";
 
 /**
  * Convenience function for converting raw JSON to a Postman Collection object.

diff --git a/packages/docusaurus-plugin-openapi-docs/src/openapi/utils/loadAndResolveSpec.ts b/packages/docusaurus-plugin-openapi-docs/src/openapi/utils/loadAndResolveSpec.ts
@@ -13,8 +13,8 @@ import chalk from "chalk";
 // @ts-ignore
 import { convertObj } from "swagger2openapi";
 
-import { OpenApiObject } from "../types";
 import { OpenAPIParser } from "./services/OpenAPIParser";
+import { OpenApiObject } from "../types";
 
 function serializer(replacer: any, cycleReplacer: any) {
   var stack: any = [],

diff --git a/packages/docusaurus-plugin-openapi-docs/src/openapi/utils/services/OpenAPIParser.ts b/packages/docusaurus-plugin-openapi-docs/src/openapi/utils/services/OpenAPIParser.ts
@@ -7,11 +7,11 @@
 
 // @ts-nocheck
 
+import { RedocNormalizedOptions } from "./RedocNormalizedOptions";
 import { OpenAPIRef, OpenAPISchema, OpenAPISpec, Referenced } from "../types";
 import { isArray, isBoolean } from "../utils/helpers";
 import { JsonPointer } from "../utils/JsonPointer";
 import { getDefinitionName, isNamedDefinition } from "../utils/openapi";
-import { RedocNormalizedOptions } from "./RedocNormalizedOptions";
 
 export type MergedOpenAPISchema = OpenAPISchema & { parentRefs?: string[] };
 

diff --git a/packages/docusaurus-plugin-openapi-docs/src/openapi/utils/utils/openapi.ts b/packages/docusaurus-plugin-openapi-docs/src/openapi/utils/utils/openapi.ts
@@ -9,6 +9,13 @@
 
 import { dirname } from "path";
 
+import {
+  isNumeric,
+  removeQueryString,
+  resolveUrl,
+  isArray,
+  isBoolean,
+} from "./helpers";
 import { OpenAPIParser } from "../services/OpenAPIParser";
 import {
   OpenAPIEncoding,
@@ -21,13 +28,6 @@ import {
   OpenAPIServer,
   Referenced,
 } from "../types";
-import {
-  isNumeric,
-  removeQueryString,
-  resolveUrl,
-  isArray,
-  isBoolean,
-} from "./helpers";
 
 function isWildcardStatusCode(
   statusCode: string | number

diff --git a/packages/docusaurus-theme-openapi-docs/package.json b/packages/docusaurus-theme-openapi-docs/package.json
@@ -49,7 +49,7 @@
     "file-saver": "^2.0.5",
     "lodash": "^4.17.20",
     "node-polyfill-webpack-plugin": "^2.0.1",
-    "prism-react-renderer": "^2.1.0",
+    "prism-react-renderer": "^2.3.0",
     "react-hook-form": "^7.43.8",
     "react-live": "^4.0.0",
     "react-magic-dropzone": "^1.0.1",

diff --git a/packages/docusaurus-theme-openapi-docs/src/markdown/utils.ts b/packages/docusaurus-theme-openapi-docs/src/markdown/utils.ts
@@ -5,7 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-export type Children = string | undefined | (string | undefined)[];
+import { ReactNode } from "react";
+
+export type Children = ReactNode | string | undefined | (string | undefined)[];
 
 export type Props = Record<string, any> & { children?: Children };
 
@@ -35,7 +37,7 @@ export function render(children: Children): string {
   if (Array.isArray(children)) {
     return children.filter((c) => c !== undefined).join("");
   }
-  return children ?? "";
+  return (children as string) ?? "";
 }
 
 export function toString(value: any): string | undefined {