docusaurus-plugin-openapi-docs 0.0.0-740 → 0.0.0-751

package/lib/markdown/createSchema.js

@@ -11,6 +11,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createNodes = exports.mergeAllOf = void 0;
 const clsx_1 = __importDefault(require("clsx"));
+const isEmpty_1 = __importDefault(require("lodash/isEmpty"));
 const createArrayBracket_1 = require("./createArrayBracket");
 const createDescription_1 = require("./createDescription");
 const createDetails_1 = require("./createDetails");
@@ -141,70 +142,52 @@ function createProperties(schema) {
  * For handling additionalProperties.
  */
 function createAdditionalProperties(schema) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
+    var _a;
     const additionalProperties = schema.additionalProperties;
-    const type = additionalProperties === null || additionalProperties === void 0 ? void 0 : additionalProperties.type;
+    if (!additionalProperties)
+        return [];
     // Handle free-form objects
-    if (String(additionalProperties) === "true" && schema.type === "object") {
+    if (additionalProperties === true || (0, isEmpty_1.default)(additionalProperties)) {
         return (0, utils_1.create)("SchemaItem", {
             name: "property name*",
             required: false,
             schemaName: "any",
-            qualifierMessage: (0, schema_1.getQualifierMessage)(schema.additionalProperties),
+            qualifierMessage: (0, schema_1.getQualifierMessage)(schema),
             schema: schema,
             collapsible: false,
             discriminator: false,
         });
     }
-    if ((type === "object" || type === "array") &&
-        ((additionalProperties === null || additionalProperties === void 0 ? void 0 : additionalProperties.properties) ||
-            (additionalProperties === null || additionalProperties === void 0 ? void 0 : additionalProperties.items) ||
-            (additionalProperties === null || additionalProperties === void 0 ? void 0 : additionalProperties.allOf) ||
-            (additionalProperties === null || additionalProperties === void 0 ? void 0 : additionalProperties.additionalProperties) ||
-            (additionalProperties === null || additionalProperties === void 0 ? void 0 : additionalProperties.oneOf) ||
-            (additionalProperties === null || additionalProperties === void 0 ? void 0 : additionalProperties.anyOf))) {
+    // objects, arrays, complex schemas
+    if (additionalProperties.properties ||
+        additionalProperties.items ||
+        additionalProperties.allOf ||
+        additionalProperties.additionalProperties ||
+        additionalProperties.oneOf ||
+        additionalProperties.anyOf) {
         const title = additionalProperties.title;
         const schemaName = (0, schema_1.getSchemaName)(additionalProperties);
         const required = (_a = schema.required) !== null && _a !== void 0 ? _a : false;
         return createDetailsNode("property name*", title !== null && title !== void 0 ? title : schemaName, additionalProperties, required, schema.nullable);
     }
-    if (((_b = schema.additionalProperties) === null || _b === void 0 ? void 0 : _b.type) === "string" ||
-        ((_c = schema.additionalProperties) === null || _c === void 0 ? void 0 : _c.type) === "object" ||
-        ((_d = schema.additionalProperties) === null || _d === void 0 ? void 0 : _d.type) === "boolean" ||
-        ((_e = schema.additionalProperties) === null || _e === void 0 ? void 0 : _e.type) === "integer" ||
-        ((_f = schema.additionalProperties) === null || _f === void 0 ? void 0 : _f.type) === "number") {
-        const additionalProperties = (_g = schema.additionalProperties) === null || _g === void 0 ? void 0 : _g.additionalProperties;
-        if (additionalProperties !== undefined) {
-            const type = (_j = (_h = schema.additionalProperties) === null || _h === void 0 ? void 0 : _h.additionalProperties) === null || _j === void 0 ? void 0 : _j.type;
-            const schemaName = (0, schema_1.getSchemaName)((_k = schema.additionalProperties) === null || _k === void 0 ? void 0 : _k.additionalProperties);
-            return (0, utils_1.create)("SchemaItem", {
-                name: "property name*",
-                required: false,
-                schemaName: schemaName !== null && schemaName !== void 0 ? schemaName : type,
-                qualifierMessage: (_l = schema.additionalProperties) !== null && _l !== void 0 ? _l : (0, schema_1.getQualifierMessage)(schema.additionalProperties),
-                schema: schema,
-                collapsible: false,
-                discriminator: false,
-            });
-        }
-        const schemaName = (0, schema_1.getSchemaName)(schema.additionalProperties);
+    // primitive types
+    if (additionalProperties.type === "string" ||
+        additionalProperties.type === "boolean" ||
+        additionalProperties.type === "integer" ||
+        additionalProperties.type === "number") {
+        const schemaName = (0, schema_1.getSchemaName)(additionalProperties);
         return (0, utils_1.create)("SchemaItem", {
             name: "property name*",
             required: false,
             schemaName: schemaName,
             qualifierMessage: (0, schema_1.getQualifierMessage)(schema),
-            schema: schema.additionalProperties,
+            schema: additionalProperties,
             collapsible: false,
             discriminator: false,
         });
     }
-    return Object.entries(schema.additionalProperties).map(([key, val]) => createEdges({
-        name: key,
-        schema: val,
-        required: Array.isArray(schema.required)
-            ? schema.required.includes(key)
-            : false,
-    }));
+    // unknown
+    return [];
 }
 /**
  * For handling items.
@@ -593,7 +576,10 @@ function createNodes(schema, schemaType) {
     }
     if (schema.allOf !== undefined) {
         const { mergedSchemas } = mergeAllOf(schema.allOf);
-        // allOf seems to always result in properties
+        if (mergedSchemas.oneOf !== undefined ||
+            mergedSchemas.anyOf !== undefined) {
+            nodes.push(createAnyOneOf(mergedSchemas));
+        }
         if (mergedSchemas.properties !== undefined) {
             nodes.push(createProperties(mergedSchemas));
         }

package/lib/markdown/createSchema.test.js

@@ -32,7 +32,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const prettier = __importStar(require("prettier"));
 const createSchema_1 = require("./createSchema");
 describe("createNodes", () => {
-    it("should create readable MODs for oneOf primitive properties", () => {
+    it("should create readable MODs for oneOf primitive properties", async () => {
         const schema = {
             "x-tags": ["clown"],
             type: "object",
@@ -69,6 +69,82 @@ describe("createNodes", () => {
                 },
             },
         };
-        expect((0, createSchema_1.createNodes)(schema, "request").map((md) => prettier.format(md, { parser: "babel" }))).toMatchSnapshot();
+        expect(await Promise.all((0, createSchema_1.createNodes)(schema, "request").map(async (md) => await prettier.format(md, { parser: "babel" })))).toMatchSnapshot();
+    });
+    describe("additionalProperties", () => {
+        it.each([
+            [
+                {
+                    allOf: [
+                        {
+                            oneOf: [
+                                {
+                                    type: "object",
+                                    properties: {
+                                        type: {
+                                            type: "string",
+                                            enum: ["nose"],
+                                        },
+                                    },
+                                    required: ["type"],
+                                },
+                                {
+                                    type: "object",
+                                    properties: {
+                                        type: {
+                                            type: "string",
+                                            enum: ["mouth"],
+                                        },
+                                    },
+                                    required: ["type"],
+                                },
+                                {
+                                    type: "object",
+                                    properties: {
+                                        type: {
+                                            type: "string",
+                                            enum: ["eyes"],
+                                        },
+                                        default: {
+                                            type: "string",
+                                        },
+                                    },
+                                    required: ["type"],
+                                },
+                            ],
+                        },
+                        {
+                            type: "object",
+                            properties: {
+                                description: {
+                                    type: "string",
+                                    description: "Description of the body part.",
+                                },
+                            },
+                            required: ["description"],
+                        },
+                    ],
+                },
+            ],
+            [
+                {
+                    type: "array",
+                    items: { type: "object", properties: { a: "string", b: "number" } },
+                },
+            ],
+            [{ type: "string" }],
+            [{ type: "number" }],
+            [{ type: "integer" }],
+            [{ type: "boolean" }],
+            [false],
+            [true],
+            [{}],
+        ])("should handle additionalProperties: %p", async (additionalProperties) => {
+            const schema = {
+                type: "object",
+                additionalProperties,
+            };
+            expect(await Promise.all((0, createSchema_1.createNodes)(schema, "request").map(async (md) => await prettier.format(md, { parser: "babel" })))).toMatchSnapshot();
+        });
     });
 });

package/lib/markdown/createVersionBadge.js

@@ -13,7 +13,7 @@ function createVersionBadge(version) {
         (0, utils_1.create)("span", {
             className: "theme-doc-version-badge badge badge--secondary",
             children: `Version: ${escape(version)}`,
-        }),
+        }, { inline: true }),
         `\n\n`,
     ]);
 }

package/lib/markdown/index.js

@@ -39,9 +39,10 @@ function createApiPageMD({ title, api: { deprecated, "x-deprecated-description":
         `import SchemaItem from "@theme/SchemaItem";\n`,
         `import SchemaTabs from "@theme/SchemaTabs";\n`,
         `import Markdown from "@theme/Markdown";\n`,
+        `import Heading from "@theme/Heading";\n`,
         `import OperationTabs from "@theme/OperationTabs";\n`,
         `import TabItem from "@theme/TabItem";\n\n`,
-        (0, createHeading_1.createHeading)(title.replace(utils_1.lessThan, "<").replace(utils_1.greaterThan, ">")),
+        (0, createHeading_1.createHeading)(title),
         (0, createMethodEndpoint_1.createMethodEndpoint)(method, path),
         infoPath && (0, createAuthorization_1.createAuthorization)(infoPath),
         frontMatter.show_extensions
@@ -66,12 +67,13 @@ exports.createApiPageMD = createApiPageMD;
 function createInfoPageMD({ info: { title, version, description, contact, license, termsOfService, logo, darkLogo, }, securitySchemes, downloadUrl, }) {
     return (0, utils_1.render)([
         `import ApiLogo from "@theme/ApiLogo";\n`,
+        `import Heading from "@theme/Heading";\n`,
         `import SchemaTabs from "@theme/SchemaTabs";\n`,
         `import TabItem from "@theme/TabItem";\n`,
         `import Export from "@theme/ApiExplorer/Export";\n\n`,
         (0, createVersionBadge_1.createVersionBadge)(version),
         (0, createDownload_1.createDownload)(downloadUrl),
-        (0, createHeading_1.createHeading)(title.replace(utils_1.lessThan, "<").replace(utils_1.greaterThan, ">")),
+        (0, createHeading_1.createHeading)(title),
         (0, createLogo_1.createLogo)(logo, darkLogo),
         (0, createDescription_1.createDescription)(description),
         (0, createAuthentication_1.createAuthentication)(securitySchemes),
@@ -91,6 +93,7 @@ function createSchemaPageMD({ schema }) {
         `import DiscriminatorTabs from "@theme/DiscriminatorTabs";\n`,
         `import SchemaItem from "@theme/SchemaItem";\n`,
         `import SchemaTabs from "@theme/SchemaTabs";\n`,
+        `import Heading from "@theme/Heading";\n`,
         `import TabItem from "@theme/TabItem";\n\n`,
         (0, createHeading_1.createHeading)(title.replace(utils_1.lessThan, "<").replace(utils_1.greaterThan, ">")),
         (0, createDescription_1.createDescription)(description),

package/lib/markdown/utils.d.ts

@@ -2,7 +2,10 @@ export type Children = string | undefined | (string | string[] | undefined)[];
 export type Props = Record<string, any> & {
     children?: Children;
 };
-export declare function create(tag: string, props: Props): string;
+export type Options = {
+    inline?: boolean;
+};
+export declare function create(tag: string, props: Props, options?: Options): string;
 export declare function guard<T>(value: T | undefined, cb: (value: T) => Children): string;
 export declare function render(children: Children): string;
 export declare const lessThan: RegExp;

package/lib/markdown/utils.js

@@ -7,13 +7,20 @@
  * ========================================================================== */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.clean = exports.codeBlock = exports.curlyBrackets = exports.codeFence = exports.greaterThan = exports.lessThan = exports.render = exports.guard = exports.create = void 0;
-function create(tag, props) {
+function create(tag, props, options = {}) {
     const { children, ...rest } = props;
     let propString = "";
     for (const [key, value] of Object.entries(rest)) {
-        propString += ` ${key}={${JSON.stringify(value)}}`;
+        propString += `\n  ${key}={${JSON.stringify(value)}}`;
     }
-    return `<${tag}${propString}>${render(children)}</${tag}>`;
+    let indentedChildren = render(children).replace(/^/gm, "  ");
+    if (options.inline) {
+        propString += `\n  children={${JSON.stringify(children)}}`;
+        indentedChildren = "";
+    }
+    propString += propString ? "\n" : "";
+    indentedChildren += indentedChildren ? "\n" : "";
+    return `<${tag}${propString}>\n${indentedChildren}</${tag}>`;
 }
 exports.create = create;
 function guard(value, cb) {
@@ -35,7 +42,7 @@ function render(children) {
 }
 exports.render = render;
 // Regex to selectively URL-encode '>' and '<' chars
-exports.lessThan = /<(?!(=|button|\s?\/button|code|\s?\/code|details|\s?\/details|summary|\s?\/summary|hr|\s?\/hr|br|\s?\/br|span|\s?\/span|strong|\s?\/strong|small|\s?\/small|table|\s?\/table|thead|\s?\/thead|tbody|\s?\/tbody|td|\s?\/td|tr|\s?\/tr|th|\s?\/th|h1|\s?\/h1|h2|\s?\/h2|h3|\s?\/h3|h4|\s?\/h4|h5|\s?\/h5|h6|\s?\/h6|title|\s?\/title|p|\s?\/p|em|\s?\/em|b|\s?\/b|i|\s?\/i|u|\s?\/u|strike|\s?\/strike|bold|\s?\/bold|a|\s?\/a|table|\s?\/table|li|\s?\/li|ol|\s?\/ol|ul|\s?\/ul|img|\s?\/img|svg|\s?\/svg|div|\s?\/div|center|\s?\/center))/gu;
+exports.lessThan = /<=?(?!(=|button|\s?\/button|code|\s?\/code|details|\s?\/details|summary|\s?\/summary|hr|\s?\/hr|br|\s?\/br|span|\s?\/span|strong|\s?\/strong|small|\s?\/small|table|\s?\/table|thead|\s?\/thead|tbody|\s?\/tbody|td|\s?\/td|tr|\s?\/tr|th|\s?\/th|h1|\s?\/h1|h2|\s?\/h2|h3|\s?\/h3|h4|\s?\/h4|h5|\s?\/h5|h6|\s?\/h6|title|\s?\/title|p|\s?\/p|em|\s?\/em|b|\s?\/b|i|\s?\/i|u|\s?\/u|strike|\s?\/strike|bold|\s?\/bold|a|\s?\/a|table|\s?\/table|li|\s?\/li|ol|\s?\/ol|ul|\s?\/ul|img|\s?\/img|svg|\s?\/svg|div|\s?\/div|center|\s?\/center))/gu;
 exports.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;
 exports.codeFence = /`{1,3}[\s\S]*?`{1,3}/g;
 exports.curlyBrackets = /([{}])/g;

package/lib/openapi/types.d.ts

@@ -269,7 +269,7 @@ export type SchemaObject = Omit<JSONSchema, "type" | "allOf" | "oneOf" | "anyOf"
     not?: SchemaObject;
     items?: SchemaObject;
     properties?: Map<SchemaObject>;
-    additionalProperties?: Map<SchemaObject>;
+    additionalProperties?: boolean | SchemaObject;
     nullable?: boolean;
     discriminator?: DiscriminatorObject;
     readOnly?: boolean;

package/lib/openapi/utils/utils/openapi.js

@@ -534,7 +534,7 @@ exports.setSecuritySchemePrefix = setSecuritySchemePrefix;
 const shortenHTTPVerb = (verb) => ({
     delete: "del",
     options: "opts",
-}[verb] || verb);
+})[verb] || verb;
 exports.shortenHTTPVerb = shortenHTTPVerb;
 function isRedocExtension(key) {
     const redocExtensions = {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "0.0.0-740",
+  "version": "0.0.0-751",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -28,24 +28,26 @@
     "watch": "tsc --watch"
   },
   "devDependencies": {
-    "@docusaurus/types": ">=2.4.1 <=2.4.3",
+    "@docusaurus/types": "^3.0.1",
     "@types/fs-extra": "^9.0.13",
     "@types/json-pointer": "^1.0.31",
     "@types/json-schema": "^7.0.9",
     "@types/lodash": "^4.14.176",
-    "@types/mustache": "^4.1.2"
+    "@types/mustache": "^4.1.2",
+    "eslint-plugin-prettier": "^5.0.1"
   },
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "^11.5.4",
-    "@docusaurus/plugin-content-docs": ">=2.4.1 <=2.4.3",
-    "@docusaurus/utils": ">=2.4.1 <=2.4.3",
-    "@docusaurus/utils-validation": ">=2.4.1 <=2.4.3",
+    "@docusaurus/plugin-content-docs": "^3.0.1",
+    "@docusaurus/utils": "^3.0.1",
+    "@docusaurus/utils-validation": "^3.0.1",
     "@redocly/openapi-core": "^1.10.5",
     "chalk": "^4.1.2",
     "clsx": "^1.1.1",
     "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",
     "openapi-to-postmanv2": "^4.21.0",
@@ -60,5 +62,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "ffc1156c334baa55d6abe7a181caae853556f2b0"
+  "gitHead": "87427f0ab49405d1aef03436e5c5babc9641dd45"
 }

package/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 {
@@ -166,21 +167,26 @@ export default function pluginOpenAPIDocs(
           tagGroups
         );
 
-        const sidebarSliceTemplate = `module.exports = {{{slice}}};`;
+        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),
+          slice: JSON5.stringify(
+            { apisidebar: sidebarSlice },
+            { space: 2, quote: '"' }
+          ),
         });
 
-        if (!fs.existsSync(`${outputDir}/sidebar.js`)) {
+        if (!fs.existsSync(`${outputDir}/sidebar.ts`)) {
           try {
-            fs.writeFileSync(`${outputDir}/sidebar.js`, view, "utf8");
+            fs.writeFileSync(`${outputDir}/sidebar.ts`, view, "utf8");
             console.log(
-              chalk.green(`Successfully created "${outputDir}/sidebar.js"`)
+              chalk.green(`Successfully created "${outputDir}/sidebar.ts"`)
             );
           } catch (err) {
             console.error(
-              chalk.red(`Failed to write "${outputDir}/sidebar.js"`),
+              chalk.red(`Failed to write "${outputDir}/sidebar.ts"`),
               chalk.yellow(err)
             );
           }
@@ -473,11 +479,7 @@ custom_edit_url: null
       cwd: path.resolve(apiDir),
       deep: 1,
     });
-    const schemaMdxFiles = await Globby(["*.schema.mdx"], {
-      cwd: path.resolve(apiDir, "schemas"),
-      deep: 1,
-    });
-    const sidebarFile = await Globby(["sidebar.{js,ts}"], {
+    const sidebarFile = await Globby(["sidebar.js", "sidebar.ts"], {
       cwd: path.resolve(apiDir),
       deep: 1,
     });
@@ -494,20 +496,17 @@ custom_edit_url: null
       })
     );
 
-    schemaMdxFiles.map((mdx) =>
-      fs.unlink(`${apiDir}/schemas/${mdx}`, (err) => {
-        if (err) {
-          console.error(
-            chalk.red(`Cleanup failed for "${apiDir}/schemas/${mdx}"`),
-            chalk.yellow(err)
-          );
-        } else {
-          console.log(
-            chalk.green(`Cleanup succeeded for "${apiDir}/schemas/${mdx}"`)
-          );
-        }
-      })
-    );
+    try {
+      fs.rmSync(`${apiDir}/schemas`, { recursive: true });
+      console.log(chalk.green(`Cleanup succeeded for "${apiDir}/schemas"`));
+    } catch (err: any) {
+      if (err.code !== "ENOENT") {
+        console.error(
+          chalk.red(`Cleanup failed for "${apiDir}/schemas"`),
+          chalk.yellow(err)
+        );
+      }
+    }
 
     sidebarFile.map((sidebar) =>
       fs.unlink(`${apiDir}/${sidebar}`, (err) => {
@@ -538,7 +537,11 @@ custom_edit_url: null
 
     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"`)
       );
@@ -574,7 +577,7 @@ custom_edit_url: null
       cli
         .command(`gen-api-docs`)
         .description(
-          `Generates OpenAPI docs in MDX file format and sidebar.js (if enabled).`
+          `Generates OpenAPI docs in MDX file format and sidebar.ts (if enabled).`
         )
         .usage("<id>")
         .arguments("<id>")
@@ -632,7 +635,7 @@ custom_edit_url: null
       cli
         .command(`gen-api-docs:version`)
         .description(
-          `Generates versioned OpenAPI docs in MDX file format, versions.js and sidebar.js (if enabled).`
+          `Generates versioned OpenAPI docs in MDX file format, versions.js and sidebar.ts (if enabled).`
         )
         .usage("<id:version>")
         .arguments("<id:version>")
@@ -724,7 +727,7 @@ custom_edit_url: null
       cli
         .command(`clean-api-docs`)
         .description(
-          `Clears the generated OpenAPI docs MDX files and sidebar.js (if enabled).`
+          `Clears the generated OpenAPI docs MDX files and sidebar.ts (if enabled).`
         )
         .usage("<id>")
         .arguments("<id>")
@@ -775,7 +778,7 @@ custom_edit_url: null
       cli
         .command(`clean-api-docs:version`)
         .description(
-          `Clears the versioned, generated OpenAPI docs MDX files, versions.json and sidebar.js (if enabled).`
+          `Clears the versioned, generated OpenAPI docs MDX files, versions.json and sidebar.ts (if enabled).`
         )
         .usage("<id:version>")
         .arguments("<id:version>")