docusaurus-plugin-openapi-docs 0.0.0-406 → 0.0.0-409

package/lib/markdown/createSchemaDetails.js

@@ -86,12 +86,14 @@ function createAnyOneOf(schema) {
     });
 }
 function createProperties(schema) {
+    const discriminator = schema.discriminator;
     return Object.entries(schema.properties).map(([key, val]) => createEdges({
         name: key,
         schema: val,
         required: Array.isArray(schema.required)
             ? schema.required.includes(key)
             : false,
+        discriminator,
     }));
 }
 function createAdditionalProperties(schema) {
@@ -228,6 +230,93 @@ function createItems(schema) {
             : false,
     }));
 }
+/**
+ * For handling discriminators that do not map to a same-level property
+ */
+function createDiscriminator(schema) {
+    var _a;
+    const discriminator = schema.discriminator;
+    const propertyName = discriminator === null || discriminator === void 0 ? void 0 : discriminator.propertyName;
+    const propertyType = "string"; // should always be string
+    const mapping = discriminator === null || discriminator === void 0 ? void 0 : discriminator.mapping;
+    // Explicit mapping is required since we can't support implicit
+    if (mapping === undefined) {
+        return undefined;
+    }
+    // Attempt to get the property description we want to display
+    // TODO: how to make it predictable when handling allOf
+    let propertyDescription;
+    const firstMappingSchema = mapping[Object.keys(mapping)[0]];
+    if (firstMappingSchema.properties !== undefined) {
+        propertyDescription =
+            firstMappingSchema.properties[propertyName].description;
+    }
+    if (firstMappingSchema.allOf !== undefined) {
+        const { mergedSchemas } = mergeAllOf(firstMappingSchema.allOf);
+        if (mergedSchemas.properties !== undefined) {
+            propertyDescription =
+                (_a = mergedSchemas.properties[propertyName]) === null || _a === void 0 ? void 0 : _a.description;
+        }
+    }
+    if (propertyDescription === undefined) {
+        if (schema.properties !== undefined &&
+            schema.properties[propertyName] !== undefined) {
+            propertyDescription = schema.properties[propertyName].description;
+        }
+    }
+    return (0, utils_1.create)("li", {
+        className: "discriminatorItem",
+        children: (0, utils_1.create)("div", {
+            children: [
+                (0, utils_1.create)("strong", {
+                    style: { paddingLeft: "1rem" },
+                    children: propertyName,
+                }),
+                (0, utils_1.guard)(propertyType, (name) => (0, utils_1.create)("span", {
+                    style: { opacity: "0.6" },
+                    children: ` ${propertyType}`,
+                })),
+                (0, utils_1.guard)((0, schema_1.getQualifierMessage)(schema.discriminator), (message) => (0, utils_1.create)("div", {
+                    style: {
+                        paddingLeft: "1rem",
+                    },
+                    children: (0, createDescription_1.createDescription)(message),
+                })),
+                (0, utils_1.guard)(propertyDescription, (description) => (0, utils_1.create)("div", {
+                    style: {
+                        paddingLeft: "1rem",
+                    },
+                    children: (0, createDescription_1.createDescription)(description),
+                })),
+                (0, utils_1.create)("DiscriminatorTabs", {
+                    children: Object.keys(mapping).map((key, index) => {
+                        if (mapping[key].allOf !== undefined) {
+                            const { mergedSchemas } = mergeAllOf(mapping[key].allOf);
+                            // Cleanup duplicate property from mapping schema
+                            delete mergedSchemas.properties[propertyName];
+                            mapping[key] = mergedSchemas;
+                        }
+                        if (mapping[key].properties !== undefined) {
+                            // Cleanup duplicate property from mapping schema
+                            delete mapping[key].properties[propertyName];
+                        }
+                        const label = key;
+                        return (0, utils_1.create)("TabItem", {
+                            label: label,
+                            value: `${index}-item-discriminator`,
+                            children: [
+                                (0, utils_1.create)("div", {
+                                    style: { marginLeft: "-4px" },
+                                    children: createNodes(mapping[key]),
+                                }),
+                            ],
+                        });
+                    }),
+                }),
+            ],
+        }),
+    });
+}
 function createDetailsNode(name, schemaName, schema, required) {
     return (0, utils_1.create)("SchemaItem", {
         collapsible: true,
@@ -272,12 +361,75 @@ function createDetailsNode(name, schemaName, schema, required) {
         ],
     });
 }
+/**
+ * For handling discriminators that map to a same-level property (like 'petType').
+ * Note: These should only be encountered while iterating through properties.
+ */
+function createPropertyDiscriminator(name, schemaName, schema, discriminator, required) {
+    if (schema === undefined) {
+        return undefined;
+    }
+    if (discriminator.mapping === undefined) {
+        return undefined;
+    }
+    return (0, utils_1.create)("li", {
+        className: "discriminatorItem",
+        children: (0, utils_1.create)("div", {
+            children: [
+                (0, utils_1.create)("strong", { style: { paddingLeft: "1rem" }, children: name }),
+                (0, utils_1.guard)(schemaName, (name) => (0, utils_1.create)("span", {
+                    style: { opacity: "0.6" },
+                    children: ` ${schemaName}`,
+                })),
+                (0, utils_1.guard)(required, () => [
+                    (0, utils_1.create)("strong", {
+                        style: {
+                            fontSize: "var(--ifm-code-font-size)",
+                            color: "var(--openapi-required)",
+                        },
+                        children: " required",
+                    }),
+                ]),
+                (0, utils_1.guard)((0, schema_1.getQualifierMessage)(discriminator), (message) => (0, utils_1.create)("div", {
+                    style: {
+                        paddingLeft: "1rem",
+                    },
+                    children: (0, createDescription_1.createDescription)(message),
+                })),
+                (0, utils_1.guard)(schema.description, (description) => (0, utils_1.create)("div", {
+                    style: {
+                        paddingLeft: "1rem",
+                    },
+                    children: (0, createDescription_1.createDescription)(description),
+                })),
+                (0, utils_1.create)("DiscriminatorTabs", {
+                    children: Object.keys(discriminator === null || discriminator === void 0 ? void 0 : discriminator.mapping).map((key, index) => {
+                        const label = key;
+                        return (0, utils_1.create)("TabItem", {
+                            label: label,
+                            value: `${index}-item-discriminator`,
+                            children: [
+                                (0, utils_1.create)("div", {
+                                    style: { marginLeft: "-4px" },
+                                    children: createNodes(discriminator === null || discriminator === void 0 ? void 0 : discriminator.mapping[key]),
+                                }),
+                            ],
+                        });
+                    }),
+                }),
+            ],
+        }),
+    });
+}
 /**
  * Creates the edges or "leaves" of a schema tree. Edges can branch into sub-nodes with createDetails().
  */
-function createEdges({ name, schema, required }) {
+function createEdges({ name, schema, required, discriminator, }) {
     var _a;
     const schemaName = (0, schema_1.getSchemaName)(schema);
+    if (discriminator !== undefined && discriminator.propertyName === name) {
+        return createPropertyDiscriminator(name, "string", schema, discriminator, required);
+    }
     if (schema.oneOf !== undefined || schema.anyOf !== undefined) {
         return createDetailsNode(name, schemaName, schema, required);
     }
@@ -327,6 +479,9 @@ function createEdges({ name, schema, required }) {
  * Creates a hierarchical level of a schema tree. Nodes produce edges that can branch into sub-nodes with edges, recursively.
  */
 function createNodes(schema) {
+    if (schema.discriminator !== undefined) {
+        return createDiscriminator(schema);
+    }
     if (schema.oneOf !== undefined || schema.anyOf !== undefined) {
         return createAnyOneOf(schema);
     }

package/lib/markdown/index.js

@@ -25,6 +25,7 @@ function createApiPageMD({ title, api: { deprecated, "x-deprecated-description":
         `import SchemaItem from "@theme/SchemaItem"\n`,
         `import ApiTabs from "@theme/ApiTabs";\n`,
         `import SchemaTabs from "@theme/SchemaTabs";\n`,
+        `import DiscriminatorTabs from "@theme/DiscriminatorTabs";\n`,
         `import TabItem from "@theme/TabItem";\n\n`,
         `## ${(0, lodash_1.escape)(title)}\n\n`,
         (0, createDeprecationNotice_1.createDeprecationNotice)({ deprecated, description: deprecatedDescription }),

package/lib/markdown/schema.js

@@ -61,12 +61,25 @@ function getQualifierMessage(schema) {
     let qualifierGroups = [];
     if (schema.minLength || schema.maxLength) {
         let lengthQualifier = "";
-        if (schema.minLength) {
-            lengthQualifier += `${schema.minLength} ≤ `;
+        let minLength;
+        let maxLength;
+        if (schema.minLength && schema.minLength > 1) {
+            minLength = `\`>= ${schema.minLength} characters\``;
+        }
+        if (schema.minLength && schema.minLength === 1) {
+            minLength = `\`non-empty\``;
         }
-        lengthQualifier += "length";
         if (schema.maxLength) {
-            lengthQualifier += ` ≤ ${schema.maxLength}`;
+            maxLength = `\`<= ${schema.maxLength} characters\``;
+        }
+        if (minLength && !maxLength) {
+            lengthQualifier += minLength;
+        }
+        if (maxLength && !minLength) {
+            lengthQualifier += maxLength;
+        }
+        if (minLength && maxLength) {
+            lengthQualifier += `${minLength} and ${maxLength}`;
         }
         qualifierGroups.push(lengthQualifier);
     }
@@ -75,38 +88,54 @@ function getQualifierMessage(schema) {
         typeof schema.exclusiveMinimum === "number" ||
         typeof schema.exclusiveMaximum === "number") {
         let minmaxQualifier = "";
+        let minimum;
+        let maximum;
         if (typeof schema.exclusiveMinimum === "number") {
-            minmaxQualifier += `${schema.exclusiveMinimum} < `;
+            minimum = `\`> ${schema.exclusiveMinimum}\``;
         }
         else if (schema.minimum && !schema.exclusiveMinimum) {
-            minmaxQualifier += `${schema.minimum} ≤ `;
+            minimum = `\`>= ${schema.minimum}\``;
         }
         else if (schema.minimum && schema.exclusiveMinimum === true) {
-            minmaxQualifier += `${schema.minimum} < `;
+            minimum = `\`> ${schema.minimum}\``;
         }
-        minmaxQualifier += "value";
         if (typeof schema.exclusiveMaximum === "number") {
-            minmaxQualifier += ` < ${schema.exclusiveMaximum}`;
+            maximum = `\`< ${schema.exclusiveMaximum}\``;
         }
         else if (schema.maximum && !schema.exclusiveMaximum) {
-            minmaxQualifier += ` ≤ ${schema.maximum}`;
+            maximum = `\`<= ${schema.maximum}\``;
         }
         else if (schema.maximum && schema.exclusiveMaximum === true) {
-            minmaxQualifier += ` < ${schema.maximum}`;
+            maximum = `\`< ${schema.maximum}\``;
+        }
+        if (minimum && !maximum) {
+            minmaxQualifier += minimum;
+        }
+        if (maximum && !minimum) {
+            minmaxQualifier += maximum;
+        }
+        if (minimum && maximum) {
+            minmaxQualifier += `${minimum} and ${maximum}`;
         }
         qualifierGroups.push(minmaxQualifier);
     }
     if (schema.pattern) {
         qualifierGroups.push(`Value must match regular expression \`${schema.pattern}\``);
     }
+    // Check if discriminator mapping
+    const discriminator = schema;
+    if (discriminator.mapping) {
+        const values = Object.keys(discriminator.mapping);
+        qualifierGroups.push(`[${values.map((e) => `\`${e}\``).join(", ")}]`);
+    }
     if (schema.enum) {
         qualifierGroups.push(`[${schema.enum.map((e) => `\`${e}\``).join(", ")}]`);
     }
     if (schema.minItems) {
-        qualifierGroups.push(`items >= ${schema.minItems}`);
+        qualifierGroups.push(`\`>= ${schema.minItems}\``);
     }
     if (schema.maxItems) {
-        qualifierGroups.push(`items <= ${schema.maxItems}`);
+        qualifierGroups.push(`\`<= ${schema.maxItems}\``);
     }
     if (qualifierGroups.length === 0) {
         return undefined;

package/lib/markdown/schema.test.js

@@ -16,17 +16,17 @@ describe("getQualifierMessage", () => {
     // minLength + maxLength
     //
     it("should render minLength", () => {
-        const expected = "**Possible values:** 1 ≤ length";
+        const expected = "**Possible values:** `non-empty`";
         const actual = (0, schema_1.getQualifierMessage)({ minLength: 1 });
         expect(actual).toBe(expected);
     });
     it("should render maxLength", () => {
-        const expected = "**Possible values:** length ≤ 40";
+        const expected = "**Possible values:** `<= 40 characters`";
         const actual = (0, schema_1.getQualifierMessage)({ maxLength: 40 });
         expect(actual).toBe(expected);
     });
     it("should render minLength and maxLength", () => {
-        const expected = "**Possible values:** 1 ≤ length ≤ 40";
+        const expected = "**Possible values:** `non-empty` and `<= 40 characters`";
         const actual = (0, schema_1.getQualifierMessage)({ minLength: 1, maxLength: 40 });
         expect(actual).toBe(expected);
     });
@@ -39,7 +39,7 @@ describe("getQualifierMessage", () => {
         expect(actual).toBe(expected);
     });
     it("should render multiple string qualifiers", () => {
-        const expected = "**Possible values:** 1 ≤ length ≤ 40, Value must match regular expression `^[a-zA-Z0-9_-]*$`";
+        const expected = "**Possible values:** `non-empty` and `<= 40 characters`, Value must match regular expression `^[a-zA-Z0-9_-]*$`";
         const actual = (0, schema_1.getQualifierMessage)({
             minLength: 1,
             maxLength: 40,
@@ -59,42 +59,42 @@ describe("getQualifierMessage", () => {
     // minimum + maximum + exclusiveMinimum + exclusiveMaximum
     //
     it("should render minimum", () => {
-        const expected = "**Possible values:** 1 ≤ value";
+        const expected = "**Possible values:** `>= 1`";
         const actual = (0, schema_1.getQualifierMessage)({ minimum: 1 });
         expect(actual).toBe(expected);
     });
     it("should render maximum", () => {
-        const expected = "**Possible values:** value ≤ 40";
+        const expected = "**Possible values:** `<= 40`";
         const actual = (0, schema_1.getQualifierMessage)({ maximum: 40 });
         expect(actual).toBe(expected);
     });
     it("should render numeric exclusiveMinimum", () => {
-        const expected = "**Possible values:** 1 < value";
+        const expected = "**Possible values:** `> 1`";
         const actual = (0, schema_1.getQualifierMessage)({ exclusiveMinimum: 1 });
         expect(actual).toBe(expected);
     });
     it("should render numeric exclusiveMaximum", () => {
-        const expected = "**Possible values:** value < 40";
+        const expected = "**Possible values:** `< 40`";
         const actual = (0, schema_1.getQualifierMessage)({ exclusiveMaximum: 40 });
         expect(actual).toBe(expected);
     });
     it("should render boolean exclusiveMinimum", () => {
-        const expected = "**Possible values:** 1 < value";
+        const expected = "**Possible values:** `> 1`";
         const actual = (0, schema_1.getQualifierMessage)({ minimum: 1, exclusiveMinimum: true });
         expect(actual).toBe(expected);
     });
     it("should render boolean exclusiveMaximum", () => {
-        const expected = "**Possible values:** value < 40";
+        const expected = "**Possible values:** `< 40`";
         const actual = (0, schema_1.getQualifierMessage)({ maximum: 40, exclusiveMaximum: true });
         expect(actual).toBe(expected);
     });
     it("should render minimum when exclusiveMinimum is false", () => {
-        const expected = "**Possible values:** 1 ≤ value";
+        const expected = "**Possible values:** `>= 1`";
         const actual = (0, schema_1.getQualifierMessage)({ minimum: 1, exclusiveMinimum: false });
         expect(actual).toBe(expected);
     });
     it("should render maximum when exclusiveMaximum is false", () => {
-        const expected = "**Possible values:** value ≤ 40";
+        const expected = "**Possible values:** `<= 40`";
         const actual = (0, schema_1.getQualifierMessage)({
             maximum: 40,
             exclusiveMaximum: false,
@@ -102,12 +102,12 @@ describe("getQualifierMessage", () => {
         expect(actual).toBe(expected);
     });
     it("should render minimum and maximum", () => {
-        const expected = "**Possible values:** 1 ≤ value ≤ 40";
+        const expected = "**Possible values:** `>= 1` and `<= 40`";
         const actual = (0, schema_1.getQualifierMessage)({ minimum: 1, maximum: 40 });
         expect(actual).toBe(expected);
     });
     it("should render boolean exclusiveMinimum and maximum", () => {
-        const expected = "**Possible values:** 1 < value ≤ 40";
+        const expected = "**Possible values:** `> 1` and `<= 40`";
         const actual = (0, schema_1.getQualifierMessage)({
             minimum: 1,
             maximum: 40,
@@ -116,7 +116,7 @@ describe("getQualifierMessage", () => {
         expect(actual).toBe(expected);
     });
     it("should render minimum and boolean exclusiveMaximum", () => {
-        const expected = "**Possible values:** 1 ≤ value < 40";
+        const expected = "**Possible values:** `>= 1` and `< 40`";
         const actual = (0, schema_1.getQualifierMessage)({
             minimum: 1,
             maximum: 40,
@@ -125,7 +125,7 @@ describe("getQualifierMessage", () => {
         expect(actual).toBe(expected);
     });
     it("should render numeric exclusiveMinimum and maximum", () => {
-        const expected = "**Possible values:** 1 < value ≤ 40";
+        const expected = "**Possible values:** `> 1` and `<= 40`";
         const actual = (0, schema_1.getQualifierMessage)({
             exclusiveMinimum: 1,
             maximum: 40,
@@ -133,7 +133,7 @@ describe("getQualifierMessage", () => {
         expect(actual).toBe(expected);
     });
     it("should render minimum and numeric exclusiveMaximum", () => {
-        const expected = "**Possible values:** 1 ≤ value < 40";
+        const expected = "**Possible values:** `>= 1` and `< 40`";
         const actual = (0, schema_1.getQualifierMessage)({
             minimum: 1,
             exclusiveMaximum: 40,
@@ -141,7 +141,7 @@ describe("getQualifierMessage", () => {
         expect(actual).toBe(expected);
     });
     it("should render numeric exclusiveMinimum and boolean exclusiveMaximum", () => {
-        const expected = "**Possible values:** 1 < value < 40";
+        const expected = "**Possible values:** `> 1` and `< 40`";
         const actual = (0, schema_1.getQualifierMessage)({
             exclusiveMinimum: 1,
             maximum: 40,

package/lib/openapi/openapi.js

@@ -79,7 +79,6 @@ function createItems(openapiData, sidebarOptions) {
                 unversionedId: tagId,
                 title: description !== null && description !== void 0 ? description : "",
                 description: description !== null && description !== void 0 ? description : "",
-                slug: "/" + tagId,
                 frontMatter: {},
                 tag: {
                     ...tag,
@@ -96,7 +95,6 @@ function createItems(openapiData, sidebarOptions) {
             unversionedId: infoId,
             title: openapiData.info.title,
             description: openapiData.info.description,
-            slug: "/" + infoId,
             frontMatter: {},
             securitySchemes: (_b = openapiData.components) === null || _b === void 0 ? void 0 : _b.securitySchemes,
             info: {
@@ -144,7 +142,6 @@ function createItems(openapiData, sidebarOptions) {
                 unversionedId: baseId,
                 title: title,
                 description: description !== null && description !== void 0 ? description : "",
-                slug: "/" + baseId,
                 frontMatter: {},
                 api: {
                     ...defaults,

package/lib/openapi/utils/loadAndResolveSpec.js

@@ -15,6 +15,7 @@ const openapi_core_1 = require("@redocly/openapi-core");
 const chalk_1 = __importDefault(require("chalk"));
 // @ts-ignore
 const swagger2openapi_1 = require("swagger2openapi");
+const OpenAPIParser_1 = require("./services/OpenAPIParser");
 function serializer(replacer, cycleReplacer) {
     var stack = [], keys = [];
     if (cycleReplacer === undefined)
@@ -24,6 +25,18 @@ function serializer(replacer, cycleReplacer) {
             return value.title ? `circular(${value.title})` : "circular()";
         };
     return function (key, value) {
+        // Resolve discriminator ref pointers
+        if ((value === null || value === void 0 ? void 0 : value.discriminator) !== undefined) {
+            const parser = new OpenAPIParser_1.OpenAPIParser(stack[0]);
+            for (let [k, v] of Object.entries(value.discriminator.mapping)) {
+                const discriminator = k;
+                if (typeof v === "string" && v.charAt(0) === "#") {
+                    const ref = v;
+                    const resolvedRef = parser.byRef(ref);
+                    value.discriminator.mapping[discriminator] = resolvedRef;
+                }
+            }
+        }
         if (stack.length > 0) {
             // @ts-ignore
             var thisPos = stack.indexOf(this);

package/lib/sidebars/index.js

@@ -9,6 +9,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+const path_1 = __importDefault(require("path"));
 const clsx_1 = __importDefault(require("clsx"));
 const lodash_1 = require("lodash");
 const uniq_1 = __importDefault(require("lodash/uniq"));
@@ -98,8 +99,8 @@ function groupByTags(items, sidebarOptions, options, tags, docPath) {
                 type: "generated-index",
                 title: tag,
                 slug: label
-                    ? "/category/" + (0, lodash_1.kebabCase)(label) + "/" + (0, lodash_1.kebabCase)(tag)
-                    : "/category/" + (0, lodash_1.kebabCase)(tag),
+                    ? path_1.default.join("/category", basePath, (0, lodash_1.kebabCase)(label), (0, lodash_1.kebabCase)(tag))
+                    : path_1.default.join("/category", basePath, (0, lodash_1.kebabCase)(tag)),
             };
         }
         return {

package/lib/types.d.ts

@@ -51,7 +51,7 @@ export interface ApiMetadataBase {
     description: string;
     source: string;
     sourceDirName: string;
-    slug: string;
+    slug?: string;
     permalink: string;
     sidebarPosition?: number;
     frontMatter: Record<string, unknown>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "0.0.0-406",
+  "version": "0.0.0-409",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -67,5 +67,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "16858c4b489fc024973a4ffe42fc57ecc0c4f1a3"
+  "gitHead": "6cfbade709c0e80f79e91b3e4fa11dbf416490b5"
 }

package/src/markdown/createSchemaDetails.ts

@@ -99,6 +99,7 @@ function createAnyOneOf(schema: SchemaObject): any {
 }
 
 function createProperties(schema: SchemaObject) {
+  const discriminator = schema.discriminator;
   return Object.entries(schema.properties!).map(([key, val]) =>
     createEdges({
       name: key,
@@ -106,6 +107,7 @@ function createProperties(schema: SchemaObject) {
       required: Array.isArray(schema.required)
         ? schema.required.includes(key)
         : false,
+      discriminator,
     })
   );
 }
@@ -277,6 +279,110 @@ function createItems(schema: SchemaObject) {
   );
 }
 
+/**
+ * For handling discriminators that do not map to a same-level property
+ */
+function createDiscriminator(schema: SchemaObject) {
+  const discriminator = schema.discriminator;
+  const propertyName = discriminator?.propertyName;
+  const propertyType = "string"; // should always be string
+  const mapping: any = discriminator?.mapping;
+
+  // Explicit mapping is required since we can't support implicit
+  if (mapping === undefined) {
+    return undefined;
+  }
+
+  // Attempt to get the property description we want to display
+  // TODO: how to make it predictable when handling allOf
+  let propertyDescription;
+  const firstMappingSchema = mapping[Object.keys(mapping)[0]];
+  if (firstMappingSchema.properties !== undefined) {
+    propertyDescription =
+      firstMappingSchema.properties![propertyName!].description;
+  }
+  if (firstMappingSchema.allOf !== undefined) {
+    const { mergedSchemas }: { mergedSchemas: SchemaObject } = mergeAllOf(
+      firstMappingSchema.allOf
+    );
+    if (mergedSchemas.properties !== undefined) {
+      propertyDescription =
+        mergedSchemas.properties[propertyName!]?.description;
+    }
+  }
+
+  if (propertyDescription === undefined) {
+    if (
+      schema.properties !== undefined &&
+      schema.properties![propertyName!] !== undefined
+    ) {
+      propertyDescription = schema.properties![propertyName!].description;
+    }
+  }
+
+  return create("li", {
+    className: "discriminatorItem",
+    children: create("div", {
+      children: [
+        create("strong", {
+          style: { paddingLeft: "1rem" },
+          children: propertyName,
+        }),
+        guard(propertyType, (name) =>
+          create("span", {
+            style: { opacity: "0.6" },
+            children: ` ${propertyType}`,
+          })
+        ),
+        guard(getQualifierMessage(schema.discriminator as any), (message) =>
+          create("div", {
+            style: {
+              paddingLeft: "1rem",
+            },
+            children: createDescription(message),
+          })
+        ),
+        guard(propertyDescription, (description) =>
+          create("div", {
+            style: {
+              paddingLeft: "1rem",
+            },
+            children: createDescription(description),
+          })
+        ),
+        create("DiscriminatorTabs", {
+          children: Object.keys(mapping!).map((key, index) => {
+            if (mapping[key].allOf !== undefined) {
+              const { mergedSchemas }: { mergedSchemas: SchemaObject } =
+                mergeAllOf(mapping[key].allOf);
+              // Cleanup duplicate property from mapping schema
+              delete mergedSchemas.properties![propertyName!];
+              mapping[key] = mergedSchemas;
+            }
+
+            if (mapping[key].properties !== undefined) {
+              // Cleanup duplicate property from mapping schema
+              delete mapping[key].properties![propertyName!];
+            }
+
+            const label = key;
+            return create("TabItem", {
+              label: label,
+              value: `${index}-item-discriminator`,
+              children: [
+                create("div", {
+                  style: { marginLeft: "-4px" },
+                  children: createNodes(mapping[key]),
+                }),
+              ],
+            });
+          }),
+        }),
+      ],
+    }),
+  });
+}
+
 function createDetailsNode(
   name: string,
   schemaName: string,
@@ -331,18 +437,109 @@ function createDetailsNode(
   });
 }
 
+/**
+ * For handling discriminators that map to a same-level property (like 'petType').
+ * Note: These should only be encountered while iterating through properties.
+ */
+function createPropertyDiscriminator(
+  name: string,
+  schemaName: string,
+  schema: SchemaObject,
+  discriminator: any,
+  required: any
+): any {
+  if (schema === undefined) {
+    return undefined;
+  }
+
+  if (discriminator.mapping === undefined) {
+    return undefined;
+  }
+
+  return create("li", {
+    className: "discriminatorItem",
+    children: create("div", {
+      children: [
+        create("strong", { style: { paddingLeft: "1rem" }, children: name }),
+        guard(schemaName, (name) =>
+          create("span", {
+            style: { opacity: "0.6" },
+            children: ` ${schemaName}`,
+          })
+        ),
+        guard(required, () => [
+          create("strong", {
+            style: {
+              fontSize: "var(--ifm-code-font-size)",
+              color: "var(--openapi-required)",
+            },
+            children: " required",
+          }),
+        ]),
+        guard(getQualifierMessage(discriminator), (message) =>
+          create("div", {
+            style: {
+              paddingLeft: "1rem",
+            },
+            children: createDescription(message),
+          })
+        ),
+        guard(schema.description, (description) =>
+          create("div", {
+            style: {
+              paddingLeft: "1rem",
+            },
+            children: createDescription(description),
+          })
+        ),
+        create("DiscriminatorTabs", {
+          children: Object.keys(discriminator?.mapping!).map((key, index) => {
+            const label = key;
+            return create("TabItem", {
+              label: label,
+              value: `${index}-item-discriminator`,
+              children: [
+                create("div", {
+                  style: { marginLeft: "-4px" },
+                  children: createNodes(discriminator?.mapping[key]),
+                }),
+              ],
+            });
+          }),
+        }),
+      ],
+    }),
+  });
+}
+
 interface EdgeProps {
   name: string;
   schema: SchemaObject;
   required: boolean;
+  discriminator?: any | unknown;
 }
 
 /**
  * Creates the edges or "leaves" of a schema tree. Edges can branch into sub-nodes with createDetails().
  */
-function createEdges({ name, schema, required }: EdgeProps): any {
+function createEdges({
+  name,
+  schema,
+  required,
+  discriminator,
+}: EdgeProps): any {
   const schemaName = getSchemaName(schema);
 
+  if (discriminator !== undefined && discriminator.propertyName === name) {
+    return createPropertyDiscriminator(
+      name,
+      "string",
+      schema,
+      discriminator,
+      required
+    );
+  }
+
   if (schema.oneOf !== undefined || schema.anyOf !== undefined) {
     return createDetailsNode(name, schemaName, schema, required);
   }
@@ -409,6 +606,10 @@ function createEdges({ name, schema, required }: EdgeProps): any {
  * Creates a hierarchical level of a schema tree. Nodes produce edges that can branch into sub-nodes with edges, recursively.
  */
 function createNodes(schema: SchemaObject): any {
+  if (schema.discriminator !== undefined) {
+    return createDiscriminator(schema);
+  }
+
   if (schema.oneOf !== undefined || schema.anyOf !== undefined) {
     return createAnyOneOf(schema);
   }

package/src/markdown/index.ts

@@ -41,6 +41,7 @@ export function createApiPageMD({
     `import SchemaItem from "@theme/SchemaItem"\n`,
     `import ApiTabs from "@theme/ApiTabs";\n`,
     `import SchemaTabs from "@theme/SchemaTabs";\n`,
+    `import DiscriminatorTabs from "@theme/DiscriminatorTabs";\n`,
     `import TabItem from "@theme/TabItem";\n\n`,
     `## ${escape(title)}\n\n`,
     createDeprecationNotice({ deprecated, description: deprecatedDescription }),

package/src/markdown/schema.test.ts

@@ -17,19 +17,19 @@ describe("getQualifierMessage", () => {
   // minLength + maxLength
   //
   it("should render minLength", () => {
-    const expected = "**Possible values:** 1 ≤ length";
+    const expected = "**Possible values:** `non-empty`";
     const actual = getQualifierMessage({ minLength: 1 });
     expect(actual).toBe(expected);
   });
 
   it("should render maxLength", () => {
-    const expected = "**Possible values:** length ≤ 40";
+    const expected = "**Possible values:** `<= 40 characters`";
     const actual = getQualifierMessage({ maxLength: 40 });
     expect(actual).toBe(expected);
   });
 
   it("should render minLength and maxLength", () => {
-    const expected = "**Possible values:** 1 ≤ length ≤ 40";
+    const expected = "**Possible values:** `non-empty` and `<= 40 characters`";
     const actual = getQualifierMessage({ minLength: 1, maxLength: 40 });
     expect(actual).toBe(expected);
   });
@@ -46,7 +46,7 @@ describe("getQualifierMessage", () => {
 
   it("should render multiple string qualifiers", () => {
     const expected =
-      "**Possible values:** 1 ≤ length ≤ 40, Value must match regular expression `^[a-zA-Z0-9_-]*$`";
+      "**Possible values:** `non-empty` and `<= 40 characters`, Value must match regular expression `^[a-zA-Z0-9_-]*$`";
     const actual = getQualifierMessage({
       minLength: 1,
       maxLength: 40,
@@ -68,49 +68,49 @@ describe("getQualifierMessage", () => {
   // minimum + maximum + exclusiveMinimum + exclusiveMaximum
   //
   it("should render minimum", () => {
-    const expected = "**Possible values:** 1 ≤ value";
+    const expected = "**Possible values:** `>= 1`";
     const actual = getQualifierMessage({ minimum: 1 });
     expect(actual).toBe(expected);
   });
 
   it("should render maximum", () => {
-    const expected = "**Possible values:** value ≤ 40";
+    const expected = "**Possible values:** `<= 40`";
     const actual = getQualifierMessage({ maximum: 40 });
     expect(actual).toBe(expected);
   });
 
   it("should render numeric exclusiveMinimum", () => {
-    const expected = "**Possible values:** 1 < value";
+    const expected = "**Possible values:** `> 1`";
     const actual = getQualifierMessage({ exclusiveMinimum: 1 });
     expect(actual).toBe(expected);
   });
 
   it("should render numeric exclusiveMaximum", () => {
-    const expected = "**Possible values:** value < 40";
+    const expected = "**Possible values:** `< 40`";
     const actual = getQualifierMessage({ exclusiveMaximum: 40 });
     expect(actual).toBe(expected);
   });
 
   it("should render boolean exclusiveMinimum", () => {
-    const expected = "**Possible values:** 1 < value";
+    const expected = "**Possible values:** `> 1`";
     const actual = getQualifierMessage({ minimum: 1, exclusiveMinimum: true });
     expect(actual).toBe(expected);
   });
 
   it("should render boolean exclusiveMaximum", () => {
-    const expected = "**Possible values:** value < 40";
+    const expected = "**Possible values:** `< 40`";
     const actual = getQualifierMessage({ maximum: 40, exclusiveMaximum: true });
     expect(actual).toBe(expected);
   });
 
   it("should render minimum when exclusiveMinimum is false", () => {
-    const expected = "**Possible values:** 1 ≤ value";
+    const expected = "**Possible values:** `>= 1`";
     const actual = getQualifierMessage({ minimum: 1, exclusiveMinimum: false });
     expect(actual).toBe(expected);
   });
 
   it("should render maximum when exclusiveMaximum is false", () => {
-    const expected = "**Possible values:** value ≤ 40";
+    const expected = "**Possible values:** `<= 40`";
     const actual = getQualifierMessage({
       maximum: 40,
       exclusiveMaximum: false,
@@ -119,13 +119,13 @@ describe("getQualifierMessage", () => {
   });
 
   it("should render minimum and maximum", () => {
-    const expected = "**Possible values:** 1 ≤ value ≤ 40";
+    const expected = "**Possible values:** `>= 1` and `<= 40`";
     const actual = getQualifierMessage({ minimum: 1, maximum: 40 });
     expect(actual).toBe(expected);
   });
 
   it("should render boolean exclusiveMinimum and maximum", () => {
-    const expected = "**Possible values:** 1 < value ≤ 40";
+    const expected = "**Possible values:** `> 1` and `<= 40`";
     const actual = getQualifierMessage({
       minimum: 1,
       maximum: 40,
@@ -135,7 +135,7 @@ describe("getQualifierMessage", () => {
   });
 
   it("should render minimum and boolean exclusiveMaximum", () => {
-    const expected = "**Possible values:** 1 ≤ value < 40";
+    const expected = "**Possible values:** `>= 1` and `< 40`";
     const actual = getQualifierMessage({
       minimum: 1,
       maximum: 40,
@@ -145,7 +145,7 @@ describe("getQualifierMessage", () => {
   });
 
   it("should render numeric exclusiveMinimum and maximum", () => {
-    const expected = "**Possible values:** 1 < value ≤ 40";
+    const expected = "**Possible values:** `> 1` and `<= 40`";
     const actual = getQualifierMessage({
       exclusiveMinimum: 1,
       maximum: 40,
@@ -154,7 +154,7 @@ describe("getQualifierMessage", () => {
   });
 
   it("should render minimum and numeric exclusiveMaximum", () => {
-    const expected = "**Possible values:** 1 ≤ value < 40";
+    const expected = "**Possible values:** `>= 1` and `< 40`";
     const actual = getQualifierMessage({
       minimum: 1,
       exclusiveMaximum: 40,
@@ -163,7 +163,7 @@ describe("getQualifierMessage", () => {
   });
 
   it("should render numeric exclusiveMinimum and boolean exclusiveMaximum", () => {
-    const expected = "**Possible values:** 1 < value < 40";
+    const expected = "**Possible values:** `> 1` and `< 40`";
     const actual = getQualifierMessage({
       exclusiveMinimum: 1,
       maximum: 40,

package/src/markdown/schema.ts

@@ -74,13 +74,28 @@ export function getQualifierMessage(schema?: SchemaObject): string | undefined {
 
   if (schema.minLength || schema.maxLength) {
     let lengthQualifier = "";
-    if (schema.minLength) {
-      lengthQualifier += `${schema.minLength} ≤ `;
+    let minLength;
+    let maxLength;
+    if (schema.minLength && schema.minLength > 1) {
+      minLength = `\`>= ${schema.minLength} characters\``;
+    }
+    if (schema.minLength && schema.minLength === 1) {
+      minLength = `\`non-empty\``;
     }
-    lengthQualifier += "length";
     if (schema.maxLength) {
-      lengthQualifier += ` ≤ ${schema.maxLength}`;
+      maxLength = `\`<= ${schema.maxLength} characters\``;
+    }
+
+    if (minLength && !maxLength) {
+      lengthQualifier += minLength;
+    }
+    if (maxLength && !minLength) {
+      lengthQualifier += maxLength;
     }
+    if (minLength && maxLength) {
+      lengthQualifier += `${minLength} and ${maxLength}`;
+    }
+
     qualifierGroups.push(lengthQualifier);
   }
 
@@ -91,21 +106,33 @@ export function getQualifierMessage(schema?: SchemaObject): string | undefined {
     typeof schema.exclusiveMaximum === "number"
   ) {
     let minmaxQualifier = "";
+    let minimum;
+    let maximum;
     if (typeof schema.exclusiveMinimum === "number") {
-      minmaxQualifier += `${schema.exclusiveMinimum} < `;
+      minimum = `\`> ${schema.exclusiveMinimum}\``;
     } else if (schema.minimum && !schema.exclusiveMinimum) {
-      minmaxQualifier += `${schema.minimum} ≤ `;
+      minimum = `\`>= ${schema.minimum}\``;
     } else if (schema.minimum && schema.exclusiveMinimum === true) {
-      minmaxQualifier += `${schema.minimum} < `;
+      minimum = `\`> ${schema.minimum}\``;
     }
-    minmaxQualifier += "value";
     if (typeof schema.exclusiveMaximum === "number") {
-      minmaxQualifier += ` < ${schema.exclusiveMaximum}`;
+      maximum = `\`< ${schema.exclusiveMaximum}\``;
     } else if (schema.maximum && !schema.exclusiveMaximum) {
-      minmaxQualifier += ` ≤ ${schema.maximum}`;
+      maximum = `\`<= ${schema.maximum}\``;
     } else if (schema.maximum && schema.exclusiveMaximum === true) {
-      minmaxQualifier += ` < ${schema.maximum}`;
+      maximum = `\`< ${schema.maximum}\``;
     }
+
+    if (minimum && !maximum) {
+      minmaxQualifier += minimum;
+    }
+    if (maximum && !minimum) {
+      minmaxQualifier += maximum;
+    }
+    if (minimum && maximum) {
+      minmaxQualifier += `${minimum} and ${maximum}`;
+    }
+
     qualifierGroups.push(minmaxQualifier);
   }
 
@@ -115,16 +142,23 @@ export function getQualifierMessage(schema?: SchemaObject): string | undefined {
     );
   }
 
+  // Check if discriminator mapping
+  const discriminator = schema as any;
+  if (discriminator.mapping) {
+    const values = Object.keys(discriminator.mapping);
+    qualifierGroups.push(`[${values.map((e) => `\`${e}\``).join(", ")}]`);
+  }
+
   if (schema.enum) {
     qualifierGroups.push(`[${schema.enum.map((e) => `\`${e}\``).join(", ")}]`);
   }
 
   if (schema.minItems) {
-    qualifierGroups.push(`items >= ${schema.minItems}`);
+    qualifierGroups.push(`\`>= ${schema.minItems}\``);
   }
 
   if (schema.maxItems) {
-    qualifierGroups.push(`items <= ${schema.maxItems}`);
+    qualifierGroups.push(`\`<= ${schema.maxItems}\``);
   }
 
   if (qualifierGroups.length === 0) {

package/src/openapi/openapi.ts

@@ -102,7 +102,6 @@ function createItems(
           unversionedId: tagId,
           title: description ?? "",
           description: description ?? "",
-          slug: "/" + tagId,
           frontMatter: {},
           tag: {
             ...tag,
@@ -120,7 +119,6 @@ function createItems(
       unversionedId: infoId,
       title: openapiData.info.title,
       description: openapiData.info.description,
-      slug: "/" + infoId,
       frontMatter: {},
       securitySchemes: openapiData.components?.securitySchemes,
       info: {
@@ -184,7 +182,6 @@ function createItems(
         unversionedId: baseId,
         title: title,
         description: description ?? "",
-        slug: "/" + baseId,
         frontMatter: {},
         api: {
           ...defaults,

package/src/openapi/utils/loadAndResolveSpec.ts

@@ -14,6 +14,7 @@ import chalk from "chalk";
 import { convertObj } from "swagger2openapi";
 
 import { OpenApiObject } from "../types";
+import { OpenAPIParser } from "./services/OpenAPIParser";
 
 function serializer(replacer: any, cycleReplacer: any) {
   var stack: any = [],
@@ -26,6 +27,18 @@ function serializer(replacer: any, cycleReplacer: any) {
     };
 
   return function (key: any, value: any) {
+    // Resolve discriminator ref pointers
+    if (value?.discriminator !== undefined) {
+      const parser = new OpenAPIParser(stack[0]);
+      for (let [k, v] of Object.entries(value.discriminator.mapping)) {
+        const discriminator = k as string;
+        if (typeof v === "string" && v.charAt(0) === "#") {
+          const ref = v as string;
+          const resolvedRef = parser.byRef(ref);
+          value.discriminator.mapping[discriminator] = resolvedRef;
+        }
+      }
+    }
     if (stack.length > 0) {
       // @ts-ignore
       var thisPos = stack.indexOf(this);

package/src/sidebars/index.ts

@@ -5,6 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
+import path from "path";
+
 import {
   ProcessedSidebar,
   SidebarItemCategory,
@@ -139,8 +141,8 @@ function groupByTags(
           type: "generated-index" as "generated-index",
           title: tag,
           slug: label
-            ? "/category/" + kebabCase(label) + "/" + kebabCase(tag)
-            : "/category/" + kebabCase(tag),
+            ? path.join("/category", basePath, kebabCase(label), kebabCase(tag))
+            : path.join("/category", basePath, kebabCase(tag)),
         } as SidebarItemCategoryLinkConfig;
       }
 

package/src/types.ts

@@ -76,7 +76,7 @@ export interface ApiMetadataBase {
   description: string;
   source: string; // @site aliased source => "@site/docs/folder/subFolder/subSubFolder/myDoc.md"
   sourceDirName: string; // relative to the versioned docs folder (can be ".") => "folder/subFolder/subSubFolder"
-  slug: string;
+  slug?: string;
   permalink: string;
   sidebarPosition?: number;
   frontMatter: Record<string, unknown>;