docusaurus-plugin-openapi-docs 0.0.0-405 → 0.0.0-408

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/createStatusCodes.js

@@ -8,8 +8,51 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createStatusCodes = void 0;
 const createDescription_1 = require("./createDescription");
+const createDetails_1 = require("./createDetails");
+const createDetailsSummary_1 = require("./createDetailsSummary");
 const createSchemaDetails_1 = require("./createSchemaDetails");
 const utils_1 = require("./utils");
+const utils_2 = require("./utils");
+function createResponseHeaders(responseHeaders) {
+    return (0, utils_2.guard)(responseHeaders, () => (0, utils_1.create)("ul", {
+        style: { marginLeft: "1rem" },
+        children: [
+            Object.entries(responseHeaders).map(([headerName, headerObj]) => {
+                const { description, schema: { type }, example, } = headerObj;
+                return (0, utils_1.create)("li", {
+                    class: "schemaItem",
+                    children: [
+                        (0, createDetailsSummary_1.createDetailsSummary)({
+                            children: [
+                                (0, utils_1.create)("strong", { children: headerName }),
+                                (0, utils_2.guard)(type, () => [
+                                    (0, utils_1.create)("span", {
+                                        style: { opacity: "0.6" },
+                                        children: ` ${type}`,
+                                    }),
+                                ]),
+                            ],
+                        }),
+                        (0, utils_1.create)("div", {
+                            children: [
+                                (0, utils_2.guard)(description, (description) => (0, utils_1.create)("div", {
+                                    style: {
+                                        marginTop: ".5rem",
+                                        marginBottom: ".5rem",
+                                    },
+                                    children: [
+                                        (0, utils_2.guard)(example, () => `Example: ${example}`),
+                                        (0, createDescription_1.createDescription)(description),
+                                    ],
+                                })),
+                            ],
+                        }),
+                    ],
+                });
+            }),
+        ],
+    }));
+}
 function createStatusCodes({ responses }) {
     if (responses === undefined) {
         return undefined;
@@ -22,6 +65,7 @@ function createStatusCodes({ responses }) {
         children: [
             (0, utils_1.create)("ApiTabs", {
                 children: codes.map((code) => {
+                    const responseHeaders = responses[code].headers;
                     return (0, utils_1.create)("TabItem", {
                         label: code,
                         value: code,
@@ -29,6 +73,20 @@ function createStatusCodes({ responses }) {
                             (0, utils_1.create)("div", {
                                 children: (0, createDescription_1.createDescription)(responses[code].description),
                             }),
+                            responseHeaders &&
+                                (0, createDetails_1.createDetails)({
+                                    "data-collaposed": false,
+                                    open: true,
+                                    style: { textAlign: "left" },
+                                    children: [
+                                        (0, createDetailsSummary_1.createDetailsSummary)({
+                                            children: [
+                                                (0, utils_1.create)("strong", { children: "Response Headers" }),
+                                            ],
+                                        }),
+                                        createResponseHeaders(responseHeaders),
+                                    ],
+                                }),
                             (0, utils_1.create)("div", {
                                 children: (0, createSchemaDetails_1.createSchemaDetails)({
                                     title: "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

@@ -99,6 +99,12 @@ function getQualifierMessage(schema) {
     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(", ")}]`);
     }

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-405",
+  "version": "0.0.0-408",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -67,5 +67,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "f87ea96605b968d06659143fc7bcf8628e9508b1"
+  "gitHead": "a13982ebd24d40f4a81ba75a7f1046682b2ba49b"
 }

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/createStatusCodes.ts

@@ -7,13 +7,66 @@
 
 import { ApiItem } from "../types";
 import { createDescription } from "./createDescription";
+import { createDetails } from "./createDetails";
+import { createDetailsSummary } from "./createDetailsSummary";
 import { createSchemaDetails } from "./createSchemaDetails";
 import { create } from "./utils";
+import { guard } from "./utils";
 
 interface Props {
   responses: ApiItem["responses"];
 }
 
+function createResponseHeaders(responseHeaders: any) {
+  return guard(responseHeaders, () =>
+    create("ul", {
+      style: { marginLeft: "1rem" },
+      children: [
+        Object.entries(responseHeaders).map(([headerName, headerObj]) => {
+          const {
+            description,
+            schema: { type },
+            example,
+          }: any = headerObj;
+
+          return create("li", {
+            class: "schemaItem",
+            children: [
+              createDetailsSummary({
+                children: [
+                  create("strong", { children: headerName }),
+                  guard(type, () => [
+                    create("span", {
+                      style: { opacity: "0.6" },
+                      children: ` ${type}`,
+                    }),
+                  ]),
+                ],
+              }),
+              create("div", {
+                children: [
+                  guard(description, (description) =>
+                    create("div", {
+                      style: {
+                        marginTop: ".5rem",
+                        marginBottom: ".5rem",
+                      },
+                      children: [
+                        guard(example, () => `Example: ${example}`),
+                        createDescription(description),
+                      ],
+                    })
+                  ),
+                ],
+              }),
+            ],
+          });
+        }),
+      ],
+    })
+  );
+}
+
 export function createStatusCodes({ responses }: Props) {
   if (responses === undefined) {
     return undefined;
@@ -28,6 +81,7 @@ export function createStatusCodes({ responses }: Props) {
     children: [
       create("ApiTabs", {
         children: codes.map((code) => {
+          const responseHeaders: any = responses[code].headers;
           return create("TabItem", {
             label: code,
             value: code,
@@ -35,6 +89,20 @@ export function createStatusCodes({ responses }: Props) {
               create("div", {
                 children: createDescription(responses[code].description),
               }),
+              responseHeaders &&
+                createDetails({
+                  "data-collaposed": false,
+                  open: true,
+                  style: { textAlign: "left" },
+                  children: [
+                    createDetailsSummary({
+                      children: [
+                        create("strong", { children: "Response Headers" }),
+                      ],
+                    }),
+                    createResponseHeaders(responseHeaders),
+                  ],
+                }),
               create("div", {
                 children: createSchemaDetails({
                   title: "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.ts

@@ -115,6 +115,13 @@ 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(", ")}]`);
   }

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>;