docusaurus-plugin-openapi-docs 4.1.0 → 4.3.0

package/src/markdown/createSchema.ts

@@ -5,6 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { merge } from "allof-merge";
 import clsx from "clsx";
 import isEmpty from "lodash/isEmpty";
 
@@ -19,41 +21,18 @@ import { getQualifierMessage, getSchemaName } from "./schema";
 import { create, guard } from "./utils";
 import { SchemaObject } from "../openapi/types";
 
-const jsonSchemaMergeAllOf = require("json-schema-merge-allof");
-
 let SCHEMA_TYPE: "request" | "response";
 
 /**
  * Returns a merged representation of allOf array of schemas.
  */
-export function mergeAllOf(allOf: SchemaObject[]) {
-  const mergedSchemas = jsonSchemaMergeAllOf(allOf, {
-    resolvers: {
-      readOnly: function () {
-        return true;
-      },
-      writeOnly: function () {
-        return true;
-      },
-      example: function () {
-        return true;
-      },
-      "x-examples": function () {
-        return true;
-      },
-    },
-    ignoreAdditionalProperties: true,
-  });
-
-  const mergedRequired = allOf.reduce((acc, cur) => {
-    if (Array.isArray(cur.required)) {
-      const next = [...acc, ...cur.required];
-      return next;
-    }
-    return acc;
-  }, [] as any);
+export function mergeAllOf(allOf: SchemaObject) {
+  const onMergeError = (msg: string) => {
+    console.warn(msg);
+  };
 
-  return { mergedSchemas, mergedRequired };
+  const mergedSchemas = merge(allOf, { onMergeError }) as SchemaObject;
+  return mergedSchemas;
 }
 
 /**
@@ -271,10 +250,7 @@ function createItems(schema: SchemaObject) {
 
   if (schema.items?.allOf !== undefined) {
     // TODO: figure out if and how we should pass merged required array
-    const {
-      mergedSchemas,
-    }: { mergedSchemas: SchemaObject; mergedRequired: string[] | boolean } =
-      mergeAllOf(schema.items?.allOf);
+    const mergedSchemas = mergeAllOf(schema.items) as SchemaObject;
 
     // Handles combo anyOf/oneOf + properties
     if (
@@ -683,61 +659,53 @@ function createEdges({
     );
   }
 
-  if (schema.allOf !== undefined) {
-    const { mergedSchemas }: { mergedSchemas: SchemaObject } = mergeAllOf(
-      schema.allOf
-    );
-    delete schema.allOf;
-    const combinedSchemas = { ...schema, ...mergedSchemas };
+  if (schema.items?.allOf !== undefined) {
+    const mergedSchemas = mergeAllOf(schema.items);
 
     if (SCHEMA_TYPE === "request") {
-      if (combinedSchemas.readOnly && combinedSchemas.readOnly === true) {
+      if (mergedSchemas.readOnly && mergedSchemas.readOnly === true) {
         return undefined;
       }
     }
 
     if (SCHEMA_TYPE === "response") {
-      if (combinedSchemas.writeOnly && combinedSchemas.writeOnly === true) {
+      if (mergedSchemas.writeOnly && mergedSchemas.writeOnly === true) {
         return undefined;
       }
     }
 
-    const mergedSchemaName = getSchemaName(combinedSchemas);
-
-    if (name === "eventName") {
-      console.log(mergedSchemaName, combinedSchemas);
-    }
+    const mergedSchemaName = getSchemaName(mergedSchemas);
 
     if (
-      combinedSchemas.oneOf !== undefined ||
-      combinedSchemas.anyOf !== undefined
+      mergedSchemas.oneOf !== undefined ||
+      mergedSchemas.anyOf !== undefined
     ) {
       return createDetailsNode(
         name,
         mergedSchemaName,
-        combinedSchemas,
+        mergedSchemas,
         required,
-        combinedSchemas.nullable
+        mergedSchemas.nullable
       );
     }
 
-    if (combinedSchemas.properties !== undefined) {
+    if (mergedSchemas.properties !== undefined) {
       return createDetailsNode(
         name,
         mergedSchemaName,
-        combinedSchemas,
+        mergedSchemas,
         required,
-        combinedSchemas.nullable
+        mergedSchemas.nullable
       );
     }
 
-    if (combinedSchemas.additionalProperties !== undefined) {
+    if (mergedSchemas.additionalProperties !== undefined) {
       return createDetailsNode(
         name,
         mergedSchemaName,
-        combinedSchemas,
+        mergedSchemas,
         required,
-        combinedSchemas.nullable
+        mergedSchemas.nullable
       );
     }
 
@@ -746,9 +714,9 @@ function createEdges({
       return createDetailsNode(
         name,
         mergedSchemaName,
-        combinedSchemas,
+        mergedSchemas,
         required,
-        combinedSchemas.nullable
+        mergedSchemas.nullable
       );
     }
 
@@ -757,8 +725,8 @@ function createEdges({
       name,
       required: Array.isArray(required) ? required.includes(name) : required,
       schemaName: mergedSchemaName,
-      qualifierMessage: getQualifierMessage(combinedSchemas),
-      schema: combinedSchemas,
+      qualifierMessage: getQualifierMessage(mergedSchemas),
+      schema: mergedSchemas,
     });
   }
 
@@ -815,7 +783,7 @@ export function createNodes(
   }
 
   if (schema.allOf !== undefined) {
-    const { mergedSchemas } = mergeAllOf(schema.allOf);
+    const mergedSchemas = mergeAllOf(schema) as SchemaObject;
 
     if (
       mergedSchemas.oneOf !== undefined ||

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

@@ -23,7 +23,7 @@ export function createTermsOfService(termsOfService: string | undefined) {
       }),
       create("a", {
         href: `${termsOfService}`,
-        children: termsOfService,
+        children: `{'${termsOfService}'}`,
       }),
     ],
   });

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/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.
@@ -451,6 +452,7 @@ function createItems(
                   .replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
                   .replace(/\s+$/, "")
               : "",
+            sample: JSON.stringify(sampleResponseFromSchema(schemaObject)),
           },
           schema: schemaObject,
         };

package/src/openapi/types.ts

@@ -238,6 +238,7 @@ export interface MediaTypeObject {
   example?: any;
   examples?: Map<ExampleObject>;
   encoding?: Map<EncodingObject>;
+  type?: any;
 }
 
 export interface MediaTypeObjectWithRef {

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

@@ -24,6 +24,7 @@ const markdownGenerators = Joi.object({
   createApiPageMD: Joi.function(),
   createInfoPageMD: Joi.function(),
   createTagPageMD: Joi.function(),
+  createSchemaPageMD: Joi.function(),
 });
 
 export const OptionsSchema = Joi.object({