docusaurus-plugin-openapi-docs 3.0.0-beta.1 → 3.0.0-beta.10

package/src/markdown/createCallbacks.ts

@@ -0,0 +1,101 @@
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+
+import { createDescription } from "./createDescription";
+import { createMethodEndpoint } from "./createMethodEndpoint";
+import { createRequestBodyDetails } from "./createRequestBodyDetails";
+import { createStatusCodes } from "./createStatusCodes";
+import { create } from "./utils";
+import { MediaTypeObject } from "../openapi/types";
+import { ApiItem } from "../types";
+
+interface Props {
+  callbacks: ApiItem["callbacks"];
+}
+
+interface RequestBodyProps {
+  title: string;
+  body: {
+    content?: {
+      [key: string]: MediaTypeObject;
+    };
+    description?: string;
+    required?: boolean;
+  };
+}
+
+export function createCallbacks({ callbacks }: Props) {
+  if (callbacks === undefined) {
+    return undefined;
+  }
+
+  const callbacksNames = Object.keys(callbacks);
+  if (callbacksNames.length === 0) {
+    return undefined;
+  }
+
+  return create("div", {
+    children: [
+      create("div", {
+        className: "openapi__divider",
+      }),
+      create(
+        "Heading",
+        {
+          children: "Callbacks",
+          id: "callbacks",
+          as: "h2",
+          className: "openapi-tabs__heading",
+        },
+        { inline: true }
+      ),
+      create("OperationTabs", {
+        className: "openapi-tabs__operation",
+        children: callbacksNames.flatMap((name) => {
+          const path = Object.keys(callbacks[name])[0];
+          const methods = new Map([
+            ["delete", callbacks[name][path].delete],
+            ["get", callbacks[name][path].get],
+            ["head", callbacks[name][path].head],
+            ["options", callbacks[name][path].options],
+            ["patch", callbacks[name][path].patch],
+            ["post", callbacks[name][path].post],
+            ["put", callbacks[name][path].put],
+            ["trace", callbacks[name][path].trace],
+          ]);
+
+          return Array.from(methods).flatMap(([method, operationObject]) => {
+            if (!operationObject) return [];
+
+            const { description, requestBody, responses } = operationObject;
+
+            return [
+              create("TabItem", {
+                label: `${method.toUpperCase()} ${name}`,
+                value: `${method}-${name}`,
+                children: [
+                  createMethodEndpoint(method, path),
+                  // TODO: add `deprecation notice` when markdown support is added
+                  createDescription(description),
+                  createRequestBodyDetails({
+                    title: "Body",
+                    body: requestBody,
+                  } as RequestBodyProps),
+                  createStatusCodes({
+                    id: "callbacks-responses",
+                    label: "Callbacks Responses",
+                    responses,
+                  }),
+                ],
+              }),
+            ];
+          });
+        }),
+      }),
+    ],
+  });
+}

package/src/markdown/createContactInfo.ts

@@ -5,8 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { ContactObject } from "../openapi/types";
 import { create, guard } from "./utils";
+import { ContactObject } from "../openapi/types";
 
 export function createContactInfo(contact: ContactObject) {
   if (!contact || !Object.keys(contact).length) return "";

package/src/markdown/createDeprecationNotice.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { guard, Props, render } from "./utils";
+import { clean, guard, Props, render } from "./utils";
 
 function createAdmonition({ children }: Props) {
   return `:::caution deprecated\n\n${render(children)}\n\n:::`;
@@ -23,7 +23,7 @@ export function createDeprecationNotice({
   return guard(deprecated, () =>
     createAdmonition({
       children:
-        description ??
+        clean(description) ??
         "This endpoint has been deprecated and may be replaced or removed in future versions of the API.",
     })
   );

package/src/markdown/createDescription.ts

@@ -5,16 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { greaterThan, codeFence, lessThan } from "./utils";
+import { clean } from "./utils";
 
 export function createDescription(description: string | undefined) {
-  if (!description) {
-    return "";
-  }
-  return `\n\n${description
-    .replace(lessThan, "<")
-    .replace(greaterThan, ">")
-    .replace(codeFence, function (match) {
-      return match.replace(/\\>/g, ">");
-    })}\n\n`;
+  return `\n\n${clean(description)}\n\n`;
 }

package/src/markdown/createHeading.ts

@@ -5,16 +5,19 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { create, greaterThan, lessThan } from "./utils";
+import { clean, create } from "./utils";
 
 export function createHeading(heading: string) {
   return [
-    create("h1", {
-      className: "openapi__heading",
-      children: `${heading
-        .replace(lessThan, "<")
-        .replace(greaterThan, ">")}`,
-    }),
+    create(
+      "Heading",
+      {
+        children: clean(heading),
+        as: "h1",
+        className: "openapi__heading",
+      },
+      { inline: true }
+    ),
     `\n\n`,
   ];
 }

package/src/markdown/createLicense.ts

@@ -5,8 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { LicenseObject } from "../openapi/types";
 import { create, guard } from "./utils";
+import { LicenseObject } from "../openapi/types";
 
 export function createLicense(license: LicenseObject) {
   if (!license || !Object.keys(license).length) return "";

package/src/markdown/createLogo.ts

@@ -5,8 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { LogoObject } from "../openapi/types";
 import { create, guard } from "./utils";
+import { LogoObject } from "../openapi/types";
 
 export function createLogo(
   logo: LogoObject | undefined,

package/src/markdown/createParamsDetails.ts

@@ -5,10 +5,10 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { ApiItem } from "../types";
 import { createDetails } from "./createDetails";
 import { createDetailsSummary } from "./createDetailsSummary";
 import { create } from "./utils";
+import { ApiItem } from "../types";
 
 interface Props {
   parameters: ApiItem["parameters"];

package/src/markdown/createRequestBodyDetails.ts

@@ -5,8 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { MediaTypeObject } from "../openapi/types";
 import { createRequestSchema } from "./createRequestSchema";
+import { MediaTypeObject } from "../openapi/types";
 
 interface Props {
   title: string;
@@ -19,6 +19,6 @@ interface Props {
   };
 }
 
-export function createRequestBodyDetails({ title, body }: Props): any {
+export function createRequestBodyDetails({ title, body }: Props) {
   return createRequestSchema({ title, body });
 }

package/src/markdown/createRequestHeader.ts

@@ -5,6 +5,20 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
+import { create } from "./utils";
+
 export function createRequestHeader(header: string) {
-  return `## ${header}\n\n`;
+  return [
+    create(
+      "Heading",
+      {
+        children: header,
+        id: header.replace(" ", "-").toLowerCase(),
+        as: "h2",
+        className: "openapi-tabs__heading",
+      },
+      { inline: true }
+    ),
+    `\n\n`,
+  ];
 }

package/src/markdown/createRequestSchema.ts

@@ -5,12 +5,12 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { MediaTypeObject } from "../openapi/types";
 import { createDescription } from "./createDescription";
 import { createDetails } from "./createDetails";
 import { createDetailsSummary } from "./createDetailsSummary";
 import { createNodes } from "./createSchema";
 import { create, guard } from "./utils";
+import { MediaTypeObject } from "../openapi/types";
 
 interface Props {
   style?: any;
@@ -90,7 +90,7 @@ export function createRequestSchema({ title, body, ...rest }: Props) {
                 }),
                 create("ul", {
                   style: { marginLeft: "1rem" },
-                  children: createNodes(firstBody),
+                  children: createNodes(firstBody, "request"),
                 }),
               ],
             }),
@@ -161,7 +161,7 @@ export function createRequestSchema({ title, body, ...rest }: Props) {
               }),
               create("ul", {
                 style: { marginLeft: "1rem" },
-                children: createNodes(firstBody),
+                children: createNodes(firstBody, "request"),
               }),
             ],
           }),

package/src/markdown/createResponseSchema.ts

@@ -5,7 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { MediaTypeObject } from "../openapi/types";
 import { createDescription } from "./createDescription";
 import { createDetails } from "./createDetails";
 import { createDetailsSummary } from "./createDetailsSummary";
@@ -16,6 +15,7 @@ import {
   createResponseExamples,
 } from "./createStatusCodes";
 import { create, guard } from "./utils";
+import { MediaTypeObject } from "../openapi/types";
 
 interface Props {
   style?: any;
@@ -118,7 +118,7 @@ export function createResponseSchema({ title, body, ...rest }: Props) {
                           }),
                           create("ul", {
                             style: { marginLeft: "1rem" },
-                            children: createNodes(firstBody!),
+                            children: createNodes(firstBody!, "response"),
                           }),
                         ],
                       }),

package/src/markdown/createSchema.test.ts

@@ -7,11 +7,11 @@
 
 import * as prettier from "prettier";
 
-import { SchemaObject } from "../openapi/types";
 import { createNodes } from "./createSchema";
+import { SchemaObject } from "../openapi/types";
 
 describe("createNodes", () => {
-  it("should create readable MODs for oneOf primitive properties", () => {
+  it("should create readable MODs for oneOf primitive properties", async () => {
     const schema: SchemaObject = {
       type: "object",
       properties: {
@@ -48,8 +48,10 @@ describe("createNodes", () => {
       },
     };
     expect(
-      createNodes(schema).map((md: any) =>
-        prettier.format(md, { parser: "babel" })
+      await Promise.all(
+        createNodes(schema, "request").map(
+          async (md: any) => await prettier.format(md, { parser: "babel" })
+        )
       )
     ).toMatchSnapshot();
   });

package/src/markdown/createSchema.ts

@@ -7,7 +7,6 @@
 
 import clsx from "clsx";
 
-import { SchemaObject } from "../openapi/types";
 import {
   createClosingArrayBracket,
   createOpeningArrayBracket,
@@ -17,9 +16,12 @@ import { createDetails } from "./createDetails";
 import { createDetailsSummary } from "./createDetailsSummary";
 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.
  */
@@ -29,6 +31,9 @@ export function mergeAllOf(allOf: SchemaObject[]) {
       readOnly: function () {
         return true;
       },
+      writeOnly: function () {
+        return true;
+      },
       example: function () {
         return true;
       },
@@ -39,7 +44,7 @@ export function mergeAllOf(allOf: SchemaObject[]) {
     ignoreAdditionalProperties: true,
   });
 
-  const required = allOf.reduce((acc, cur) => {
+  const mergedRequired = allOf.reduce((acc, cur) => {
     if (Array.isArray(cur.required)) {
       const next = [...acc, ...cur.required];
       return next;
@@ -47,7 +52,7 @@ export function mergeAllOf(allOf: SchemaObject[]) {
     return acc;
   }, [] as any);
 
-  return { mergedSchemas, required };
+  return { mergedSchemas, mergedRequired };
 }
 
 /**
@@ -74,7 +79,7 @@ function createAnyOneOf(schema: SchemaObject): any {
           }
 
           if (anyOneSchema.allOf !== undefined) {
-            anyOneChildren.push(createNodes(anyOneSchema));
+            anyOneChildren.push(createNodes(anyOneSchema, SCHEMA_TYPE));
             delete anyOneSchema.allOf;
           }
 
@@ -89,7 +94,7 @@ function createAnyOneOf(schema: SchemaObject): any {
             anyOneSchema.type === "integer" ||
             anyOneSchema.type === "boolean"
           ) {
-            anyOneChildren.push(createNodes(anyOneSchema));
+            anyOneChildren.push(createNodes(anyOneSchema, SCHEMA_TYPE));
           }
           if (anyOneChildren.length) {
             if (schema.type === "array") {
@@ -255,9 +260,8 @@ function createItems(schema: SchemaObject) {
     // TODO: figure out if and how we should pass merged required array
     const {
       mergedSchemas,
-    }: { mergedSchemas: SchemaObject; required: string[] } = mergeAllOf(
-      schema.items?.allOf
-    );
+    }: { mergedSchemas: SchemaObject; mergedRequired: string[] | boolean } =
+      mergeAllOf(schema.items?.allOf);
 
     // Handles combo anyOf/oneOf + properties
     if (
@@ -304,7 +308,7 @@ function createItems(schema: SchemaObject) {
   ) {
     return [
       createOpeningArrayBracket(),
-      createNodes(schema.items),
+      createNodes(schema.items, SCHEMA_TYPE),
       createClosingArrayBracket(),
     ].flat();
   }
@@ -411,7 +415,7 @@ function createDetailsNode(
                   children: createDescription(description),
                 })
               ),
-              createNodes(schema),
+              createNodes(schema, SCHEMA_TYPE),
             ],
           }),
         ],
@@ -565,7 +569,7 @@ function createPropertyDiscriminator(
               // className: "openapi-tabs__discriminator-item",
               label: label,
               value: `${index}-item-discriminator`,
-              children: [createNodes(discriminator?.mapping[key])],
+              children: [createNodes(discriminator?.mapping[key], SCHEMA_TYPE)],
             });
           }),
         }),
@@ -591,7 +595,6 @@ function createEdges({
   discriminator,
 }: EdgeProps): any {
   const schemaName = getSchemaName(schema);
-
   if (discriminator !== undefined && discriminator.propertyName === name) {
     return createPropertyDiscriminator(
       name,
@@ -613,13 +616,10 @@ function createEdges({
   }
 
   if (schema.allOf !== undefined) {
-    const {
-      mergedSchemas,
-      required,
-    }: { mergedSchemas: SchemaObject; required: string[] | boolean } =
-      mergeAllOf(schema.allOf);
+    const { mergedSchemas }: { mergedSchemas: SchemaObject } = mergeAllOf(
+      schema.allOf
+    );
     const mergedSchemaName = getSchemaName(mergedSchemas);
-
     if (
       mergedSchemas.oneOf !== undefined ||
       mergedSchemas.anyOf !== undefined
@@ -664,16 +664,24 @@ function createEdges({
       );
     }
 
-    if (mergedSchemas.readOnly && mergedSchemas.readOnly === true) {
-      return undefined;
+    if (SCHEMA_TYPE === "request") {
+      if (mergedSchemas.readOnly && mergedSchemas.readOnly === true) {
+        return undefined;
+      }
+    }
+
+    if (SCHEMA_TYPE === "response") {
+      if (mergedSchemas.writeOnly && mergedSchemas.writeOnly === true) {
+        return undefined;
+      }
     }
 
     return create("SchemaItem", {
       collapsible: false,
       name,
       required: Array.isArray(required) ? required.includes(name) : required,
-      schemaName: schemaName,
-      qualifierMessage: getQualifierMessage(schema),
+      schemaName: mergedSchemaName,
+      qualifierMessage: getQualifierMessage(mergedSchemas),
       schema: mergedSchemas,
     });
   }
@@ -719,8 +727,16 @@ function createEdges({
     );
   }
 
-  if (schema.readOnly && schema.readOnly === true) {
-    return undefined;
+  if (SCHEMA_TYPE === "request") {
+    if (schema.readOnly && schema.readOnly === true) {
+      return undefined;
+    }
+  }
+
+  if (SCHEMA_TYPE === "response") {
+    if (schema.writeOnly && schema.writeOnly === true) {
+      return undefined;
+    }
   }
 
   // primitives and array of non-objects
@@ -737,7 +753,11 @@ function createEdges({
 /**
  * Creates a hierarchical level of a schema tree. Nodes produce edges that can branch into sub-nodes with edges, recursively.
  */
-export function createNodes(schema: SchemaObject): any {
+export function createNodes(
+  schema: SchemaObject,
+  schemaType: "request" | "response"
+): any {
+  SCHEMA_TYPE = schemaType;
   const nodes = [];
   // if (schema.discriminator !== undefined) {
   //   return createDiscriminator(schema);
@@ -792,9 +812,18 @@ export function createNodes(schema: SchemaObject): any {
       style: {
         marginTop: ".5rem",
         marginBottom: ".5rem",
-        marginLeft: "1rem",
       },
-      children: createDescription(schema.type),
+      children: [
+        createDescription(schema.type),
+        guard(getQualifierMessage(schema), (message) =>
+          create("div", {
+            style: {
+              paddingTop: "1rem",
+            },
+            children: createDescription(message),
+          })
+        ),
+      ],
     });
   }
 
@@ -804,9 +833,18 @@ export function createNodes(schema: SchemaObject): any {
       style: {
         marginTop: ".5rem",
         marginBottom: ".5rem",
-        marginLeft: "1rem",
       },
-      children: [createDescription(schema)],
+      children: [
+        createDescription(schema),
+        guard(getQualifierMessage(schema), (message) =>
+          create("div", {
+            style: {
+              paddingTop: "1rem",
+            },
+            children: createDescription(message),
+          })
+        ),
+      ],
     });
   }
 

package/src/markdown/createStatusCodes.ts

@@ -7,14 +7,14 @@
 
 import format from "xml-formatter";
 
-import { sampleResponseFromSchema } from "../openapi/createResponseExample";
-import { ApiItem } from "../types";
 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) {
   var toXml = function (v: any, name: string, ind: any) {
@@ -54,6 +54,8 @@ export default function json2xml(o: any, tab: any) {
 }
 
 interface Props {
+  id?: string;
+  label?: string;
   responses: ApiItem["responses"];
 }
 
@@ -125,7 +127,7 @@ export function createResponseExamples(
           value: `${exampleName}`,
           children: [
             guard(exampleValue.summary, (summary) => [
-              create("p", {
+              create("Markdown", {
                 children: ` ${summary}`,
               }),
             ]),
@@ -141,7 +143,7 @@ export function createResponseExamples(
         value: `${exampleName}`,
         children: [
           guard(exampleValue.summary, (summary) => [
-            create("p", {
+            create("Markdown", {
               children: ` ${summary}`,
             }),
           ]),
@@ -169,7 +171,7 @@ export function createResponseExample(responseExample: any, mimeType: string) {
       value: `Example`,
       children: [
         guard(responseExample.summary, (summary) => [
-          create("p", {
+          create("Markdown", {
             children: ` ${summary}`,
           }),
         ]),
@@ -185,7 +187,7 @@ export function createResponseExample(responseExample: any, mimeType: string) {
     value: `Example`,
     children: [
       guard(responseExample.summary, (summary) => [
-        create("p", {
+        create("Markdown", {
           children: ` ${summary}`,
         }),
       ]),
@@ -254,7 +256,7 @@ export function createExampleFromSchema(schema: any, mimeType: string) {
   return undefined;
 }
 
-export function createStatusCodes({ responses }: Props) {
+export function createStatusCodes({ label, id, responses }: Props) {
   if (responses === undefined) {
     return undefined;
   }
@@ -269,6 +271,8 @@ export function createStatusCodes({ responses }: Props) {
       create("div", {
         children: [
           create("ApiTabs", {
+            label,
+            id,
             children: codes.map((code) => {
               const responseHeaders: any = responses[code].headers;
               return create("TabItem", {

package/src/markdown/createVersionBadge.ts

@@ -9,10 +9,14 @@ import { create, guard } from "./utils";
 
 export function createVersionBadge(version: string | undefined) {
   return guard(version, (version) => [
-    create("span", {
-      className: "theme-doc-version-badge badge badge--secondary",
-      children: `Version: ${escape(version)}`,
-    }),
+    create(
+      "span",
+      {
+        className: "theme-doc-version-badge badge badge--secondary",
+        children: `Version: ${escape(version)}`,
+      },
+      { inline: true }
+    ),
     `\n\n`,
   ]);
 }