docusaurus-plugin-openapi-docs 4.0.0 → 4.1.0

package/src/markdown/createSchema.ts

@@ -104,6 +104,11 @@ function createAnyOneOf(schema: SchemaObject): any {
             delete anyOneSchema.allOf;
           }
 
+          if (anyOneSchema.oneOf !== undefined) {
+            anyOneChildren.push(createNodes(anyOneSchema, SCHEMA_TYPE));
+            delete anyOneSchema.oneOf;
+          }
+
           if (anyOneSchema.items !== undefined) {
             anyOneChildren.push(createItems(anyOneSchema));
             delete anyOneSchema.items;
@@ -411,16 +416,16 @@ function createDetailsNode(
           create("div", {
             style: { marginLeft: "1rem" },
             children: [
-              guard(getQualifierMessage(schema), (message) =>
+              guard(schema.description, (description) =>
                 create("div", {
                   style: { marginTop: ".5rem", marginBottom: ".5rem" },
-                  children: createDescription(message),
+                  children: createDescription(description),
                 })
               ),
-              guard(schema.description, (description) =>
+              guard(getQualifierMessage(schema), (message) =>
                 create("div", {
                   style: { marginTop: ".5rem", marginBottom: ".5rem" },
-                  children: createDescription(description),
+                  children: createDescription(message),
                 })
               ),
               createNodes(schema, SCHEMA_TYPE),
@@ -524,8 +529,9 @@ function createPropertyDiscriminator(
     return undefined;
   }
 
+  // render as a simple property if there's no mapping
   if (discriminator.mapping === undefined) {
-    return undefined;
+    return createEdges({ name, schema, required });
   }
 
   return create("div", {
@@ -553,20 +559,20 @@ function createPropertyDiscriminator(
             ]),
           ],
         }),
-        guard(getQualifierMessage(discriminator), (message) =>
+        guard(schema.description, (description) =>
           create("div", {
             style: {
               paddingLeft: "1rem",
             },
-            children: createDescription(message),
+            children: createDescription(description),
           })
         ),
-        guard(schema.description, (description) =>
+        guard(getQualifierMessage(discriminator), (message) =>
           create("div", {
             style: {
               paddingLeft: "1rem",
             },
-            children: createDescription(description),
+            children: createDescription(message),
           })
         ),
         create("DiscriminatorTabs", {
@@ -681,50 +687,57 @@ function createEdges({
     const { mergedSchemas }: { mergedSchemas: SchemaObject } = mergeAllOf(
       schema.allOf
     );
+    delete schema.allOf;
+    const combinedSchemas = { ...schema, ...mergedSchemas };
 
     if (SCHEMA_TYPE === "request") {
-      if (mergedSchemas.readOnly && mergedSchemas.readOnly === true) {
+      if (combinedSchemas.readOnly && combinedSchemas.readOnly === true) {
         return undefined;
       }
     }
 
     if (SCHEMA_TYPE === "response") {
-      if (mergedSchemas.writeOnly && mergedSchemas.writeOnly === true) {
+      if (combinedSchemas.writeOnly && combinedSchemas.writeOnly === true) {
         return undefined;
       }
     }
 
-    const mergedSchemaName = getSchemaName(mergedSchemas);
+    const mergedSchemaName = getSchemaName(combinedSchemas);
+
+    if (name === "eventName") {
+      console.log(mergedSchemaName, combinedSchemas);
+    }
+
     if (
-      mergedSchemas.oneOf !== undefined ||
-      mergedSchemas.anyOf !== undefined
+      combinedSchemas.oneOf !== undefined ||
+      combinedSchemas.anyOf !== undefined
     ) {
       return createDetailsNode(
         name,
         mergedSchemaName,
-        mergedSchemas,
+        combinedSchemas,
         required,
-        schema.nullable
+        combinedSchemas.nullable
       );
     }
 
-    if (mergedSchemas.properties !== undefined) {
+    if (combinedSchemas.properties !== undefined) {
       return createDetailsNode(
         name,
         mergedSchemaName,
-        mergedSchemas,
+        combinedSchemas,
         required,
-        schema.nullable
+        combinedSchemas.nullable
       );
     }
 
-    if (mergedSchemas.additionalProperties !== undefined) {
+    if (combinedSchemas.additionalProperties !== undefined) {
       return createDetailsNode(
         name,
         mergedSchemaName,
-        mergedSchemas,
+        combinedSchemas,
         required,
-        schema.nullable
+        combinedSchemas.nullable
       );
     }
 
@@ -733,9 +746,9 @@ function createEdges({
       return createDetailsNode(
         name,
         mergedSchemaName,
-        mergedSchemas,
+        combinedSchemas,
         required,
-        schema.nullable
+        combinedSchemas.nullable
       );
     }
 
@@ -744,8 +757,8 @@ function createEdges({
       name,
       required: Array.isArray(required) ? required.includes(name) : required,
       schemaName: mergedSchemaName,
-      qualifierMessage: getQualifierMessage(mergedSchemas),
-      schema: mergedSchemas,
+      qualifierMessage: getQualifierMessage(combinedSchemas),
+      schema: combinedSchemas,
     });
   }
 

package/src/markdown/utils.ts

@@ -5,6 +5,10 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
+/**
+ * Children in the plugin does not accept DOM elements, when compared with Children in the theme.
+ * It is designed for rendering HTML a strings.
+ */
 export type Children = string | undefined | (string | string[] | undefined)[];
 
 export type Props = Record<string, any> & { children?: Children };

package/src/openapi/openapi.ts

@@ -269,7 +269,7 @@ function createItems(
 
   // Gather x-webhooks endpoints
   for (let [path, pathObject] of Object.entries(
-    openapiData["x-webhooks"] ?? {}
+    openapiData["x-webhooks"] ?? openapiData["webhooks"] ?? {}
   )) {
     path = "webhook";
     const { $ref, description, parameters, servers, summary, ...rest } =

package/src/openapi/types.ts

@@ -21,6 +21,7 @@ export interface OpenApiObject {
   tags?: TagObject[];
   externalDocs?: ExternalDocumentationObject;
   swagger?: string;
+  webhooks?: PathsObject;
   "x-webhooks"?: PathsObject;
   "x-tagGroups"?: TagGroupObject[];
 }
@@ -197,6 +198,7 @@ export interface ParameterObject {
   param?: Object;
   // ignoring stylings: matrix, label, form, simple, spaceDelimited,
   // pipeDelimited and deepObject
+  "x-enumDescriptions"?: Record<string, string>;
 }
 
 export interface ParameterObjectWithRef {
@@ -353,6 +355,7 @@ export type SchemaObject = Omit<
   example?: any;
   deprecated?: boolean;
   "x-tags"?: string[];
+  "x-enumDescriptions"?: Record<string, string>;
 };
 
 export type SchemaObjectWithRef = Omit<

package/src/openapi/utils/services/OpenAPIParser.ts

@@ -270,6 +270,7 @@ export class OpenAPIParser {
       const {
         type,
         enum: enumProperty,
+        "x-enumDescription": enumDescription,
         properties,
         items,
         required,

package/src/options.ts

@@ -7,12 +7,17 @@
 
 import { Joi } from "@docusaurus/utils-validation";
 
+const sidebarGenerators = Joi.object({
+  createDocItem: Joi.function(),
+});
+
 const sidebarOptions = Joi.object({
   groupPathsBy: Joi.string().valid("tag", "tagGroup"),
   categoryLinkSource: Joi.string().valid("tag", "info", "auto"),
   customProps: Joi.object(),
   sidebarCollapsible: Joi.boolean(),
   sidebarCollapsed: Joi.boolean(),
+  sidebarGenerators: sidebarGenerators,
 });
 
 const markdownGenerators = Joi.object({

package/src/sidebars/index.ts

@@ -12,7 +12,6 @@ import {
   ProcessedSidebar,
   SidebarItemCategory,
   SidebarItemCategoryLinkConfig,
-  SidebarItemDoc,
 } from "@docusaurus/plugin-content-docs/src/sidebars/types";
 import { posixPath } from "@docusaurus/utils";
 import clsx from "clsx";
@@ -27,6 +26,7 @@ import type {
   ApiMetadata,
   InfoPageMetadata,
   SchemaPageMetadata,
+  ApiDocItemGenerator,
 } from "../types";
 
 function isApiItem(item: ApiMetadata): item is ApiMetadata {
@@ -41,6 +41,37 @@ function isSchemaItem(item: ApiMetadata): item is ApiMetadata {
   return item.type === "schema";
 }
 
+const createDocItem: ApiDocItemGenerator = (
+  item,
+  { sidebarOptions: { customProps }, basePath }
+) => {
+  const sidebar_label = item.frontMatter.sidebar_label;
+  const title = item.title;
+  const id = item.type === "schema" ? `schemas/${item.id}` : item.id;
+  const className =
+    item.type === "api"
+      ? clsx(
+          {
+            "menu__list-item--deprecated": item.api.deprecated,
+            "api-method": !!item.api.method,
+          },
+          item.api.method
+        )
+      : clsx(
+          {
+            "menu__list-item--deprecated": item.schema.deprecated,
+          },
+          "schema"
+        );
+  return {
+    type: "doc" as const,
+    id: basePath === "" || undefined ? `${id}` : `${basePath}/${id}`,
+    label: (sidebar_label as string) ?? title ?? id,
+    customProps: customProps,
+    className: className ? className : undefined,
+  };
+};
+
 function groupByTags(
   items: ApiMetadata[],
   sidebarOptions: SidebarOptions,
@@ -53,12 +84,8 @@ function groupByTags(
   // Remove trailing slash before proceeding
   outputDir = outputDir.replace(/\/$/, "");
 
-  const {
-    sidebarCollapsed,
-    sidebarCollapsible,
-    customProps,
-    categoryLinkSource,
-  } = sidebarOptions;
+  const { sidebarCollapsed, sidebarCollapsible, categoryLinkSource } =
+    sidebarOptions;
 
   const apiItems = items.filter(isApiItem) as ApiPageMetadata[];
   const infoItems = items.filter(isInfoItem) as InfoPageMetadata[];
@@ -101,35 +128,13 @@ function groupByTags(
   const basePath = docPath
     ? outputDir.split(docPath!)[1].replace(/^\/+/g, "")
     : outputDir.slice(outputDir.indexOf("/", 1)).replace(/^\/+/g, "");
-  function createDocItem(
-    item: ApiPageMetadata | SchemaPageMetadata
-  ): SidebarItemDoc {
-    const sidebar_label = item.frontMatter.sidebar_label;
-    const title = item.title;
-    const id = item.type === "schema" ? `schemas/${item.id}` : item.id;
-    const className =
-      item.type === "api"
-        ? clsx(
-            {
-              "menu__list-item--deprecated": item.api.deprecated,
-              "api-method": !!item.api.method,
-            },
-            item.api.method
-          )
-        : clsx(
-            {
-              "menu__list-item--deprecated": item.schema.deprecated,
-            },
-            "schema"
-          );
-    return {
-      type: "doc" as const,
-      id: basePath === "" || undefined ? `${id}` : `${basePath}/${id}`,
-      label: (sidebar_label as string) ?? title ?? id,
-      customProps: customProps,
-      className: className ? className : undefined,
-    };
-  }
+
+  const createDocItemFnContext = {
+    sidebarOptions,
+    basePath,
+  };
+  const createDocItemFn =
+    sidebarOptions.sidebarGenerators?.createDocItem ?? createDocItem;
 
   let rootIntroDoc = undefined;
   if (infoItems.length === 1) {
@@ -208,7 +213,9 @@ function groupByTags(
         link: linkConfig,
         collapsible: sidebarCollapsible,
         collapsed: sidebarCollapsed,
-        items: [...taggedSchemaItems, ...taggedApiItems].map(createDocItem),
+        items: [...taggedSchemaItems, ...taggedApiItems].map((item) =>
+          createDocItemFn(item, createDocItemFnContext)
+        ),
       };
     })
     .filter((item) => item.items.length > 0); // Filter out any categories with no items.
@@ -216,7 +223,7 @@ function groupByTags(
   // Handle items with no tag
   const untaggedItems = apiItems
     .filter(({ api }) => api.tags === undefined || api.tags.length === 0)
-    .map(createDocItem);
+    .map((item) => createDocItemFn(item, createDocItemFnContext));
   let untagged: SidebarItemCategory[] = [];
   if (untaggedItems.length > 0) {
     untagged = [
@@ -227,7 +234,7 @@ function groupByTags(
         collapsed: sidebarCollapsed!,
         items: apiItems
           .filter(({ api }) => api.tags === undefined || api.tags.length === 0)
-          .map(createDocItem),
+          .map((item) => createDocItemFn(item, createDocItemFnContext)),
       },
     ];
   }
@@ -242,7 +249,7 @@ function groupByTags(
         collapsed: sidebarCollapsed!,
         items: schemaItems
           .filter(({ schema }) => !schema["x-tags"])
-          .map(createDocItem),
+          .map((item) => createDocItemFn(item, createDocItemFnContext)),
       },
     ];
   }

package/src/types.ts

@@ -5,6 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
+import { SidebarItemDoc } from "@docusaurus/plugin-content-docs/src/sidebars/types";
 import type Request from "postman-collection";
 
 import {
@@ -57,12 +58,22 @@ export interface MarkdownGenerator {
   createSchemaPageMD?: (pageData: SchemaPageMetadata) => string;
 }
 
+export type ApiDocItemGenerator = (
+  item: ApiPageMetadata | SchemaPageMetadata,
+  context: { sidebarOptions: SidebarOptions; basePath: string }
+) => SidebarItemDoc;
+
+export interface SidebarGenerators {
+  createDocItem?: ApiDocItemGenerator;
+}
+
 export interface SidebarOptions {
   groupPathsBy?: string;
   categoryLinkSource?: "info" | "tag" | "auto";
   customProps?: { [key: string]: unknown };
   sidebarCollapsible?: boolean;
   sidebarCollapsed?: boolean;
+  sidebarGenerators?: SidebarGenerators;
 }
 
 export interface APIVersionOptions {