docusaurus-plugin-openapi-docs 4.0.1 → 4.2.0

package/src/markdown/createStatusCodes.ts

@@ -5,15 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import format from "xml-formatter";
-
-import { createDescription } from "./createDescription";
-import { createDetails } from "./createDetails";
-import { createDetailsSummary } from "./createDetailsSummary";
-import { createResponseSchema } from "./createResponseSchema";
 import { create } from "./utils";
-import { guard } from "./utils";
-import { sampleResponseFromSchema } from "../openapi/createResponseExample";
 import { ApiItem } from "../types";
 
 export default function json2xml(o: any, tab: any) {
@@ -59,264 +51,13 @@ interface Props {
   responses: ApiItem["responses"];
 }
 
-function createResponseHeaders(responseHeaders: any) {
-  return guard(responseHeaders, () =>
-    create("ul", {
-      style: { marginLeft: "1rem" },
-      children: [
-        Object.entries(responseHeaders).map(
-          ([headerName, headerObj]: [any, any]) => {
-            const { description, example }: any = headerObj;
-            const type = headerObj.schema?.type ?? "any";
-
-            return create("li", {
-              className: "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 createResponseExamples(
-  responseExamples: any,
-  mimeType: string
-) {
-  let language = "shell";
-  if (mimeType.endsWith("json")) {
-    language = "json";
-  }
-  if (mimeType.endsWith("xml")) {
-    language = "xml";
-  }
-  return Object.entries(responseExamples).map(
-    ([exampleName, exampleValue]: any) => {
-      if (typeof exampleValue.value === "object") {
-        return create("TabItem", {
-          label: `${exampleName}`,
-          value: `${exampleName}`,
-          children: [
-            guard(exampleValue.summary, (summary) => [
-              create("div", {
-                children: `${summary}`,
-                className: "openapi-example__summary",
-              }),
-            ]),
-            create("ResponseSamples", {
-              responseExample: JSON.stringify(exampleValue.value, null, 2),
-              language: language,
-            }),
-          ],
-        });
-      }
-      return create("TabItem", {
-        label: `${exampleName}`,
-        value: `${exampleName}`,
-        children: [
-          guard(exampleValue.summary, (summary) => [
-            create("div", {
-              children: `${summary}`,
-              className: "openapi-example__summary",
-            }),
-          ]),
-          create("ResponseSamples", {
-            responseExample: exampleValue.value,
-            language: language,
-          }),
-        ],
-      });
-    }
-  );
-}
-
-export function createResponseExample(responseExample: any, mimeType: string) {
-  let language = "shell";
-  if (mimeType.endsWith("json")) {
-    language = "json";
-  }
-  if (mimeType.endsWith("xml")) {
-    language = "xml";
-  }
-  if (typeof responseExample === "object") {
-    return create("TabItem", {
-      label: `Example`,
-      value: `Example`,
-      children: [
-        guard(responseExample.summary, (summary) => [
-          create("div", {
-            children: `${summary}`,
-            className: "openapi-example__summary",
-          }),
-        ]),
-        create("ResponseSamples", {
-          responseExample: JSON.stringify(responseExample, null, 2),
-          language: language,
-        }),
-      ],
-    });
-  }
-  return create("TabItem", {
-    label: `Example`,
-    value: `Example`,
-    children: [
-      guard(responseExample.summary, (summary) => [
-        create("div", {
-          children: `${summary}`,
-          className: "openapi-example__summary",
-        }),
-      ]),
-      create("ResponseSamples", {
-        responseExample: responseExample,
-        language: language,
-      }),
-    ],
-  });
-}
-
-export function createExampleFromSchema(schema: any, mimeType: string) {
-  const responseExample = sampleResponseFromSchema(schema);
-  if (mimeType.endsWith("xml")) {
-    let responseExampleObject;
-    try {
-      responseExampleObject = JSON.parse(JSON.stringify(responseExample));
-    } catch {
-      return undefined;
-    }
-
-    if (typeof responseExampleObject === "object") {
-      let xmlExample;
-      try {
-        xmlExample = format(json2xml(responseExampleObject, ""), {
-          indentation: "  ",
-          lineSeparator: "\n",
-          collapseContent: true,
-        });
-      } catch {
-        const xmlExampleWithRoot = { root: responseExampleObject };
-        try {
-          xmlExample = format(json2xml(xmlExampleWithRoot, ""), {
-            indentation: "  ",
-            lineSeparator: "\n",
-            collapseContent: true,
-          });
-        } catch {
-          xmlExample = json2xml(responseExampleObject, "");
-        }
-      }
-      return create("TabItem", {
-        label: `Example (from schema)`,
-        value: `Example (from schema)`,
-        children: [
-          create("ResponseSamples", {
-            responseExample: xmlExample,
-            language: "xml",
-          }),
-        ],
-      });
-    }
-  }
-  if (typeof responseExample === "object") {
-    return create("TabItem", {
-      label: `Example (from schema)`,
-      value: `Example (from schema)`,
-      children: [
-        create("ResponseSamples", {
-          responseExample: JSON.stringify(responseExample, null, 2),
-          language: "json",
-        }),
-      ],
-    });
-  }
-  return undefined;
-}
-
-export function createStatusCodes({ label, id, responses }: Props) {
-  if (responses === undefined) {
-    return undefined;
-  }
-
-  const codes = Object.keys(responses);
-  if (codes.length === 0) {
-    return undefined;
-  }
-
-  return create("div", {
-    children: [
-      create("div", {
-        children: [
-          create("ApiTabs", {
-            label,
-            id,
-            children: codes.map((code) => {
-              const responseHeaders: any = responses[code].headers;
-              return create("TabItem", {
-                label: code,
-                value: code,
-                children: [
-                  create("div", {
-                    children: createDescription(responses[code].description),
-                  }),
-                  responseHeaders &&
-                    createDetails({
-                      className: "openapi-markdown__details",
-                      "data-collapsed": true,
-                      open: false,
-                      style: { textAlign: "left", marginBottom: "1rem" },
-                      children: [
-                        createDetailsSummary({
-                          children: [
-                            create("strong", {
-                              children: "Response Headers",
-                            }),
-                          ],
-                        }),
-                        createResponseHeaders(responseHeaders),
-                      ],
-                    }),
-                  create("div", {
-                    children: createResponseSchema({
-                      title: "Schema",
-                      body: {
-                        content: responses[code].content,
-                      },
-                    }),
-                  }),
-                ],
-              });
-            }),
-          }),
-        ],
-      }),
-    ],
-  });
+export function createStatusCodes({ id, label, responses }: Props) {
+  return [
+    create("StatusCodes", {
+      id: id,
+      label: label,
+      responses: responses,
+    }),
+    "\n\n",
+  ];
 }

package/src/markdown/index.ts

@@ -19,7 +19,6 @@ import { createMethodEndpoint } from "./createMethodEndpoint";
 import { createParamsDetails } from "./createParamsDetails";
 import { createRequestBodyDetails } from "./createRequestBodyDetails";
 import { createRequestHeader } from "./createRequestHeader";
-import { createNodes } from "./createSchema";
 import { createStatusCodes } from "./createStatusCodes";
 import { createTermsOfService } from "./createTermsOfService";
 import { createVendorExtensions } from "./createVendorExtensions";
@@ -67,18 +66,13 @@ export function createApiPageMD({
   frontMatter,
 }: ApiPageMetadata) {
   return render([
-    `import ApiTabs from "@theme/ApiTabs";\n`,
-    `import DiscriminatorTabs from "@theme/DiscriminatorTabs";\n`,
     `import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";\n`,
-    `import SecuritySchemes from "@theme/ApiExplorer/SecuritySchemes";\n`,
-    `import MimeTabs from "@theme/MimeTabs";\n`,
-    `import ParamsItem from "@theme/ParamsItem";\n`,
-    `import ResponseSamples from "@theme/ResponseSamples";\n`,
-    `import SchemaItem from "@theme/SchemaItem";\n`,
-    `import SchemaTabs from "@theme/SchemaTabs";\n`,
-    `import Heading from "@theme/Heading";\n`,
+    `import ParamsDetails from "@theme/ParamsDetails";\n`,
+    `import RequestSchema from "@theme/RequestSchema";\n`,
+    `import StatusCodes from "@theme/StatusCodes";\n`,
     `import OperationTabs from "@theme/OperationTabs";\n`,
-    `import TabItem from "@theme/TabItem";\n\n`,
+    `import TabItem from "@theme/TabItem";\n`,
+    `import Heading from "@theme/Heading";\n\n`,
     createHeading(title),
     createMethodEndpoint(method, path),
     infoPath && createAuthorization(infoPath),
@@ -88,10 +82,7 @@ export function createApiPageMD({
     createDeprecationNotice({ deprecated, description: deprecatedDescription }),
     createDescription(description),
     requestBody || parameters ? createRequestHeader("Request") : undefined,
-    createParamsDetails({ parameters, type: "path" }),
-    createParamsDetails({ parameters, type: "query" }),
-    createParamsDetails({ parameters, type: "header" }),
-    createParamsDetails({ parameters, type: "cookie" }),
+    createParamsDetails({ parameters }),
     createRequestBodyDetails({
       title: "Body",
       body: requestBody,
@@ -141,15 +132,13 @@ export function createTagPageMD({ tag: { description } }: TagPageMetadata) {
 export function createSchemaPageMD({ schema }: SchemaPageMetadata) {
   const { title = "", description } = schema;
   return render([
-    `import DiscriminatorTabs from "@theme/DiscriminatorTabs";\n`,
-    `import SchemaItem from "@theme/SchemaItem";\n`,
-    `import SchemaTabs from "@theme/SchemaTabs";\n`,
-    `import Heading from "@theme/Heading";\n`,
-    `import TabItem from "@theme/TabItem";\n\n`,
+    `import Schema from "@theme/Schema";\n`,
+    `import Heading from "@theme/Heading";\n\n`,
     createHeading(title.replace(lessThan, "<").replace(greaterThan, ">")),
     createDescription(description),
-    create("ul", {
-      children: createNodes(schema, "response"),
+    create("Schema", {
+      schema: schema,
+      schemaType: "response",
     }),
   ]);
 }

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

@@ -66,9 +66,7 @@ function sampleRequestFromProp(name: string, prop: any, obj: any): any {
   } else if (prop.anyOf) {
     obj[name] = sampleRequestFromSchema(prop.anyOf[0]);
   } else if (prop.allOf) {
-    const { mergedSchemas }: { mergedSchemas: SchemaObject } = mergeAllOf(
-      prop.allOf
-    );
+    const mergedSchemas = mergeAllOf(prop) as SchemaObject;
     sampleRequestFromProp(name, mergedSchemas, obj);
   } else {
     obj[name] = sampleRequestFromSchema(prop);
@@ -107,8 +105,7 @@ export const sampleRequestFromSchema = (schema: SchemaObject = {}): any => {
     }
 
     if (allOf) {
-      const { mergedSchemas }: { mergedSchemas: SchemaObject } =
-        mergeAllOf(allOf);
+      const mergedSchemas = mergeAllOf(schemaCopy) as SchemaObject;
       if (mergedSchemas.properties) {
         for (const [key, value] of Object.entries(mergedSchemas.properties)) {
           if ((value.readOnly && value.readOnly === true) || value.deprecated) {

package/src/openapi/createResponseExample.ts

@@ -66,9 +66,7 @@ function sampleResponseFromProp(name: string, prop: any, obj: any): any {
   } else if (prop.anyOf) {
     obj[name] = sampleResponseFromSchema(prop.anyOf[0]);
   } else if (prop.allOf) {
-    const { mergedSchemas }: { mergedSchemas: SchemaObject } = mergeAllOf(
-      prop.allOf
-    );
+    const mergedSchemas = mergeAllOf(prop) as SchemaObject;
     sampleResponseFromProp(name, mergedSchemas, obj);
   } else {
     obj[name] = sampleResponseFromSchema(prop);
@@ -87,8 +85,7 @@ export const sampleResponseFromSchema = (schema: SchemaObject = {}): any => {
     }
 
     if (allOf) {
-      const { mergedSchemas }: { mergedSchemas: SchemaObject } =
-        mergeAllOf(allOf);
+      const mergedSchemas = mergeAllOf(schemaCopy) as SchemaObject;
       if (mergedSchemas.properties) {
         for (const [key, value] of Object.entries(mergedSchemas.properties)) {
           if (

package/src/openapi/openapi.ts

@@ -20,7 +20,6 @@ import sdk from "postman-collection";
 
 import { sampleRequestFromSchema } from "./createRequestExample";
 import { OpenApiObject, TagGroupObject, TagObject } from "./types";
-import { loadAndResolveSpec } from "./utils/loadAndResolveSpec";
 import { isURL } from "../index";
 import {
   ApiMetadata,
@@ -31,6 +30,8 @@ import {
   SidebarOptions,
   TagPageMetadata,
 } from "../types";
+import { sampleResponseFromSchema } from "./createResponseExample";
+import { loadAndResolveSpec } from "./utils/loadAndResolveSpec";
 
 /**
  * Convenience function for converting raw JSON to a Postman Collection object.
@@ -269,7 +270,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 } =
@@ -451,6 +452,7 @@ function createItems(
                   .replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
                   .replace(/\s+$/, "")
               : "",
+            sample: JSON.stringify(sampleResponseFromSchema(schemaObject)),
           },
           schema: schemaObject,
         };

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 {
@@ -236,6 +238,7 @@ export interface MediaTypeObject {
   example?: any;
   examples?: Map<ExampleObject>;
   encoding?: Map<EncodingObject>;
+  type?: any;
 }
 
 export interface MediaTypeObjectWithRef {
@@ -353,6 +356,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/loadAndResolveSpec.ts

@@ -13,8 +13,8 @@ import chalk from "chalk";
 // @ts-ignore
 import { convertObj } from "swagger2openapi";
 
-import { OpenAPIParser } from "./services/OpenAPIParser";
 import { OpenApiObject } from "../types";
+import { OpenAPIParser } from "./services/OpenAPIParser";
 
 function serializer(replacer: any, cycleReplacer: any) {
   var stack: any = [],

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,18 +7,24 @@
 
 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({
   createApiPageMD: Joi.function(),
   createInfoPageMD: Joi.function(),
   createTagPageMD: Joi.function(),
+  createSchemaPageMD: Joi.function(),
 });
 
 export const OptionsSchema = 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)),
       },
     ];
   }