docusaurus-plugin-openapi-docs 2.0.1 → 2.0.3

package/lib/markdown/createCallbacks.d.ts

@@ -0,0 +1,6 @@
+import { ApiItem } from "../types";
+interface Props {
+    callbacks: ApiItem["callbacks"];
+}
+export declare function createCallbacks({ callbacks }: Props): string | undefined;
+export {};

package/lib/markdown/createCallbacks.js

@@ -0,0 +1,76 @@
+"use strict";
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCallbacks = void 0;
+const createDescription_1 = require("./createDescription");
+const createMethodEndpoint_1 = require("./createMethodEndpoint");
+const createRequestBodyDetails_1 = require("./createRequestBodyDetails");
+const createStatusCodes_1 = require("./createStatusCodes");
+const utils_1 = require("./utils");
+function createCallbacks({ callbacks }) {
+    if (callbacks === undefined) {
+        return undefined;
+    }
+    const callbacksNames = Object.keys(callbacks);
+    if (callbacksNames.length === 0) {
+        return undefined;
+    }
+    return (0, utils_1.create)("div", {
+        children: [
+            (0, utils_1.create)("div", {
+                className: "openapi__divider",
+            }),
+            (0, utils_1.create)("h2", {
+                children: "Callbacks",
+                id: "callbacks",
+            }),
+            (0, utils_1.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 [
+                            (0, utils_1.create)("TabItem", {
+                                label: `${method.toUpperCase()} ${name}`,
+                                value: `${method}-${name}`,
+                                children: [
+                                    (0, createMethodEndpoint_1.createMethodEndpoint)(method, path),
+                                    // TODO: add `deprecation notice` when markdown support is added
+                                    (0, createDescription_1.createDescription)(description),
+                                    (0, createRequestBodyDetails_1.createRequestBodyDetails)({
+                                        title: "Body",
+                                        body: requestBody,
+                                    }),
+                                    (0, createStatusCodes_1.createStatusCodes)({
+                                        id: "callbacks-responses",
+                                        label: "Callbacks Responses",
+                                        responses,
+                                    }),
+                                ],
+                            }),
+                        ];
+                    });
+                }),
+            }),
+        ],
+    });
+}
+exports.createCallbacks = createCallbacks;

package/lib/markdown/createRequestBodyDetails.d.ts

@@ -9,5 +9,5 @@ interface Props {
         required?: boolean;
     };
 }
-export declare function createRequestBodyDetails({ title, body }: Props): any;
+export declare function createRequestBodyDetails({ title, body }: Props): string | undefined;
 export {};

package/lib/markdown/createStatusCodes.d.ts

@@ -1,10 +1,12 @@
 import { ApiItem } from "../types";
 export default function json2xml(o: any, tab: any): string;
 interface Props {
+    id?: string;
+    label?: string;
     responses: ApiItem["responses"];
 }
 export declare function createResponseExamples(responseExamples: any, mimeType: string): string[];
 export declare function createResponseExample(responseExample: any, mimeType: string): string;
 export declare function createExampleFromSchema(schema: any, mimeType: string): string | undefined;
-export declare function createStatusCodes({ responses }: Props): string | undefined;
+export declare function createStatusCodes({ label, id, responses }: Props): string | undefined;
 export {};

package/lib/markdown/createStatusCodes.js

@@ -118,7 +118,7 @@ function createResponseExamples(responseExamples, mimeType) {
                 value: `${exampleName}`,
                 children: [
                     (0, utils_2.guard)(exampleValue.summary, (summary) => [
-                        (0, utils_1.create)("p", {
+                        (0, utils_1.create)("Markdown", {
                             children: ` ${summary}`,
                         }),
                     ]),
@@ -134,7 +134,7 @@ function createResponseExamples(responseExamples, mimeType) {
             value: `${exampleName}`,
             children: [
                 (0, utils_2.guard)(exampleValue.summary, (summary) => [
-                    (0, utils_1.create)("p", {
+                    (0, utils_1.create)("Markdown", {
                         children: ` ${summary}`,
                     }),
                 ]),
@@ -161,7 +161,7 @@ function createResponseExample(responseExample, mimeType) {
             value: `Example`,
             children: [
                 (0, utils_2.guard)(responseExample.summary, (summary) => [
-                    (0, utils_1.create)("p", {
+                    (0, utils_1.create)("Markdown", {
                         children: ` ${summary}`,
                     }),
                 ]),
@@ -177,7 +177,7 @@ function createResponseExample(responseExample, mimeType) {
         value: `Example`,
         children: [
             (0, utils_2.guard)(responseExample.summary, (summary) => [
-                (0, utils_1.create)("p", {
+                (0, utils_1.create)("Markdown", {
                     children: ` ${summary}`,
                 }),
             ]),
@@ -248,7 +248,7 @@ function createExampleFromSchema(schema, mimeType) {
     return undefined;
 }
 exports.createExampleFromSchema = createExampleFromSchema;
-function createStatusCodes({ responses }) {
+function createStatusCodes({ label, id, responses }) {
     if (responses === undefined) {
         return undefined;
     }
@@ -261,6 +261,8 @@ function createStatusCodes({ responses }) {
             (0, utils_1.create)("div", {
                 children: [
                     (0, utils_1.create)("ApiTabs", {
+                        label,
+                        id,
                         children: codes.map((code) => {
                             const responseHeaders = responses[code].headers;
                             return (0, utils_1.create)("TabItem", {

package/lib/markdown/index.d.ts

@@ -1,4 +1,4 @@
 import { ApiPageMetadata, InfoPageMetadata, TagPageMetadata } from "../types";
-export declare function createApiPageMD({ title, api: { deprecated, "x-deprecated-description": deprecatedDescription, description, method, path, extensions, parameters, requestBody, responses, }, infoPath, frontMatter, }: ApiPageMetadata): string;
+export declare function createApiPageMD({ title, api: { deprecated, "x-deprecated-description": deprecatedDescription, description, method, path, extensions, parameters, requestBody, responses, callbacks, }, infoPath, frontMatter, }: ApiPageMetadata): string;
 export declare function createInfoPageMD({ info: { title, version, description, contact, license, termsOfService, logo, darkLogo, }, securitySchemes, downloadUrl, }: InfoPageMetadata): string;
 export declare function createTagPageMD({ tag: { description } }: TagPageMetadata): string;

package/lib/markdown/index.js

@@ -9,6 +9,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createTagPageMD = exports.createInfoPageMD = exports.createApiPageMD = void 0;
 const createAuthentication_1 = require("./createAuthentication");
 const createAuthorization_1 = require("./createAuthorization");
+const createCallbacks_1 = require("./createCallbacks");
 const createContactInfo_1 = require("./createContactInfo");
 const createDeprecationNotice_1 = require("./createDeprecationNotice");
 const createDescription_1 = require("./createDescription");
@@ -25,7 +26,7 @@ const createTermsOfService_1 = require("./createTermsOfService");
 const createVendorExtensions_1 = require("./createVendorExtensions");
 const createVersionBadge_1 = require("./createVersionBadge");
 const utils_1 = require("./utils");
-function createApiPageMD({ title, api: { deprecated, "x-deprecated-description": deprecatedDescription, description, method, path, extensions, parameters, requestBody, responses, }, infoPath, frontMatter, }) {
+function createApiPageMD({ title, api: { deprecated, "x-deprecated-description": deprecatedDescription, description, method, path, extensions, parameters, requestBody, responses, callbacks, }, infoPath, frontMatter, }) {
     return (0, utils_1.render)([
         `import ApiTabs from "@theme/ApiTabs";\n`,
         `import DiscriminatorTabs from "@theme/DiscriminatorTabs";\n`,
@@ -36,11 +37,15 @@ function createApiPageMD({ title, api: { deprecated, "x-deprecated-description":
         `import ResponseSamples from "@theme/ResponseSamples";\n`,
         `import SchemaItem from "@theme/SchemaItem";\n`,
         `import SchemaTabs from "@theme/SchemaTabs";\n`,
+        `import Markdown from "@theme/Markdown";\n`,
+        `import OperationTabs from "@theme/OperationTabs";\n`,
         `import TabItem from "@theme/TabItem";\n\n`,
         (0, createHeading_1.createHeading)(title.replace(utils_1.lessThan, "<").replace(utils_1.greaterThan, ">")),
         (0, createMethodEndpoint_1.createMethodEndpoint)(method, path),
         infoPath && (0, createAuthorization_1.createAuthorization)(infoPath),
-        frontMatter.show_extensions && (0, createVendorExtensions_1.createVendorExtensions)(extensions),
+        frontMatter.show_extensions
+            ? (0, createVendorExtensions_1.createVendorExtensions)(extensions)
+            : undefined,
         (0, createDeprecationNotice_1.createDeprecationNotice)({ deprecated, description: deprecatedDescription }),
         (0, createDescription_1.createDescription)(description),
         (0, createRequestHeader_1.createRequestHeader)("Request"),
@@ -53,6 +58,7 @@ function createApiPageMD({ title, api: { deprecated, "x-deprecated-description":
             body: requestBody,
         }),
         (0, createStatusCodes_1.createStatusCodes)({ responses }),
+        (0, createCallbacks_1.createCallbacks)({ callbacks }),
     ]);
 }
 exports.createApiPageMD = createApiPageMD;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -60,5 +60,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "6f9eff64e6b32c63100daaa7f70431edc8cf455d"
+  "gitHead": "f6641c0ce01e3247a06ef8ddde7bafbe749d4ed1"
 }

package/src/markdown/createCallbacks.ts

@@ -0,0 +1,95 @@
+/* ============================================================================
+ * 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 { MediaTypeObject } from "../openapi/types";
+import { ApiItem } from "../types";
+import { createDescription } from "./createDescription";
+import { createMethodEndpoint } from "./createMethodEndpoint";
+import { createRequestBodyDetails } from "./createRequestBodyDetails";
+import { createStatusCodes } from "./createStatusCodes";
+import { create } from "./utils";
+
+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("h2", {
+        children: "Callbacks",
+        id: "callbacks",
+      }),
+      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/createRequestBodyDetails.ts

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

@@ -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/index.ts

@@ -14,6 +14,7 @@ import {
 import { ApiPageMetadata, InfoPageMetadata, TagPageMetadata } from "../types";
 import { createAuthentication } from "./createAuthentication";
 import { createAuthorization } from "./createAuthorization";
+import { createCallbacks } from "./createCallbacks";
 import { createContactInfo } from "./createContactInfo";
 import { createDeprecationNotice } from "./createDeprecationNotice";
 import { createDescription } from "./createDescription";
@@ -31,7 +32,7 @@ import { createVendorExtensions } from "./createVendorExtensions";
 import { createVersionBadge } from "./createVersionBadge";
 import { greaterThan, lessThan, render } from "./utils";
 
-interface Props {
+interface RequestBodyProps {
   title: string;
   body: {
     content?: {
@@ -54,6 +55,7 @@ export function createApiPageMD({
     parameters,
     requestBody,
     responses,
+    callbacks,
   },
   infoPath,
   frontMatter,
@@ -68,11 +70,15 @@ export function createApiPageMD({
     `import ResponseSamples from "@theme/ResponseSamples";\n`,
     `import SchemaItem from "@theme/SchemaItem";\n`,
     `import SchemaTabs from "@theme/SchemaTabs";\n`,
+    `import Markdown from "@theme/Markdown";\n`,
+    `import OperationTabs from "@theme/OperationTabs";\n`,
     `import TabItem from "@theme/TabItem";\n\n`,
     createHeading(title.replace(lessThan, "<").replace(greaterThan, ">")),
     createMethodEndpoint(method, path),
     infoPath && createAuthorization(infoPath),
-    frontMatter.show_extensions && createVendorExtensions(extensions),
+    frontMatter.show_extensions
+      ? createVendorExtensions(extensions)
+      : undefined,
     createDeprecationNotice({ deprecated, description: deprecatedDescription }),
     createDescription(description),
     createRequestHeader("Request"),
@@ -83,8 +89,9 @@ export function createApiPageMD({
     createRequestBodyDetails({
       title: "Body",
       body: requestBody,
-    } as Props),
+    } as RequestBodyProps),
     createStatusCodes({ responses }),
+    createCallbacks({ callbacks }),
   ]);
 }