docusaurus-plugin-openapi-docs 0.0.0-619 → 0.0.0-685

package/src/markdown/createRequestSchema.ts

@@ -39,6 +39,7 @@ export function createRequestSchema({ title, body, ...rest }: Props) {
 
   if (mimeTypes && mimeTypes.length > 1) {
     return create("MimeTabs", {
+      className: "openapi-tabs__mime",
       schemaType: "request",
       children: mimeTypes.map((mimeType) => {
         const firstBody = body.content![mimeType].schema;
@@ -55,21 +56,23 @@ export function createRequestSchema({ title, body, ...rest }: Props) {
           value: `${mimeType}`,
           children: [
             createDetails({
+              className: "openapi-markdown__details mime",
               "data-collapsed": false,
               open: true,
               ...rest,
               children: [
                 createDetailsSummary({
-                  style: { textAlign: "left" },
+                  className: "openapi-markdown__details-summary-mime",
                   children: [
-                    create("strong", { children: `${title}` }),
+                    create("h3", {
+                      className:
+                        "openapi-markdown__details-summary-header-body",
+                      children: `${title}`,
+                    }),
                     guard(body.required && body.required === true, () => [
-                      create("strong", {
-                        style: {
-                          fontSize: "var(--ifm-code-font-size)",
-                          color: "var(--openapi-required)",
-                        },
-                        children: " required",
+                      create("span", {
+                        className: "openapi-schema__required",
+                        children: "required",
                       }),
                     ]),
                   ],
@@ -87,7 +90,7 @@ export function createRequestSchema({ title, body, ...rest }: Props) {
                 }),
                 create("ul", {
                   style: { marginLeft: "1rem" },
-                  children: createNodes(firstBody),
+                  children: createNodes(firstBody, "request"),
                 }),
               ],
             }),
@@ -112,20 +115,25 @@ export function createRequestSchema({ title, body, ...rest }: Props) {
     }
   }
   return create("MimeTabs", {
+    className: "openapi-tabs__mime",
     children: [
       create("TabItem", {
         label: randomFirstKey,
         value: `${randomFirstKey}-schema`,
         children: [
           createDetails({
+            className: "openapi-markdown__details mime",
             "data-collapsed": false,
             open: true,
             ...rest,
             children: [
               createDetailsSummary({
-                style: { textAlign: "left" },
+                className: "openapi-markdown__details-summary-mime",
                 children: [
-                  create("strong", { children: `${title}` }),
+                  create("h3", {
+                    className: "openapi-markdown__details-summary-header-body",
+                    children: `${title}`,
+                  }),
                   guard(firstBody.type === "array", (format) =>
                     create("span", {
                       style: { opacity: "0.6" },
@@ -134,11 +142,8 @@ export function createRequestSchema({ title, body, ...rest }: Props) {
                   ),
                   guard(body.required, () => [
                     create("strong", {
-                      style: {
-                        fontSize: "var(--ifm-code-font-size)",
-                        color: "var(--openapi-required)",
-                      },
-                      children: " required",
+                      className: "openapi-schema__required",
+                      children: "required",
                     }),
                   ]),
                 ],
@@ -156,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

@@ -44,6 +44,7 @@ export function createResponseSchema({ title, body, ...rest }: Props) {
 
   if (mimeTypes && mimeTypes.length) {
     return create("MimeTabs", {
+      className: "openapi-tabs__mime",
       schemaType: "response",
       children: mimeTypes.map((mimeType: any) => {
         const responseExamples = body.content![mimeType].examples;
@@ -70,6 +71,7 @@ export function createResponseSchema({ title, body, ...rest }: Props) {
           value: `${mimeType}`,
           children: [
             create("SchemaTabs", {
+              className: "openapi-tabs__schema",
               // TODO: determine if we should persist this
               // groupId: "schema-tabs",
               children: [
@@ -79,23 +81,22 @@ export function createResponseSchema({ title, body, ...rest }: Props) {
                     value: `${title}`,
                     children: [
                       createDetails({
+                        className: "openapi-markdown__details response",
                         "data-collapsed": false,
                         open: true,
                         ...rest,
                         children: [
                           createDetailsSummary({
-                            style: { textAlign: "left" },
+                            className:
+                              "openapi-markdown__details-summary-response",
                             children: [
                               create("strong", { children: `${title}` }),
                               guard(
                                 body.required && body.required === true,
                                 () => [
-                                  create("strong", {
-                                    style: {
-                                      fontSize: "var(--ifm-code-font-size)",
-                                      color: "var(--openapi-required)",
-                                    },
-                                    children: " required",
+                                  create("span", {
+                                    className: "openapi-schema__required",
+                                    children: "required",
                                   }),
                                 ]
                               ),
@@ -117,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

@@ -0,0 +1,56 @@
+/* ============================================================================
+ * 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 * as prettier from "prettier";
+
+import { SchemaObject } from "../openapi/types";
+import { createNodes } from "./createSchema";
+
+describe("createNodes", () => {
+  it("should create readable MODs for oneOf primitive properties", () => {
+    const schema: SchemaObject = {
+      type: "object",
+      properties: {
+        oneOfProperty: {
+          oneOf: [
+            {
+              type: "object",
+              properties: {
+                noseLength: {
+                  type: "number",
+                },
+              },
+              required: ["noseLength"],
+              description: "Clown's nose length",
+            },
+            {
+              type: "array",
+              items: {
+                type: "string",
+              },
+              description: "Array of strings",
+            },
+            {
+              type: "boolean",
+            },
+            {
+              type: "number",
+            },
+            {
+              type: "string",
+            },
+          ],
+        },
+      },
+    };
+    expect(
+      createNodes(schema, "request").map((md: any) =>
+        prettier.format(md, { parser: "babel" })
+      )
+    ).toMatchSnapshot();
+  });
+});

package/src/markdown/createSchema.ts

@@ -5,6 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
+import clsx from "clsx";
+
 import { SchemaObject } from "../openapi/types";
 import {
   createClosingArrayBracket,
@@ -18,6 +20,8 @@ import { create, guard } from "./utils";
 
 const jsonSchemaMergeAllOf = require("json-schema-merge-allof");
 
+let SCHEMA_TYPE: "request" | "response";
+
 /**
  * Returns a merged representation of allOf array of schemas.
  */
@@ -27,6 +31,9 @@ export function mergeAllOf(allOf: SchemaObject[]) {
       readOnly: function () {
         return true;
       },
+      writeOnly: function () {
+        return true;
+      },
       example: function () {
         return true;
       },
@@ -72,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;
           }
 
@@ -87,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") {
@@ -302,7 +309,7 @@ function createItems(schema: SchemaObject) {
   ) {
     return [
       createOpeningArrayBracket(),
-      createNodes(schema.items),
+      createNodes(schema.items, SCHEMA_TYPE),
       createClosingArrayBracket(),
     ].flat();
   }
@@ -338,41 +345,60 @@ function createDetailsNode(
     className: "schemaItem",
     children: [
       createDetails({
+        className: "openapi-markdown__details",
         children: [
           createDetailsSummary({
             children: [
-              create("strong", { children: name }),
               create("span", {
-                style: { opacity: "0.6" },
-                children: ` ${schemaName}`,
-              }),
-              guard(
-                (schema.nullable && schema.nullable === true) ||
-                  (nullable && nullable === true),
-                () => [
+                className: "openapi-schema__container",
+                children: [
                   create("strong", {
-                    style: {
-                      fontSize: "var(--ifm-code-font-size)",
-                      color: "var(--openapi-nullable)",
-                    },
-                    children: " nullable",
+                    className: clsx("openapi-schema__property", {
+                      "openapi-schema__strikethrough": schema.deprecated,
+                    }),
+                    children: name,
                   }),
-                ]
-              ),
-              guard(
-                Array.isArray(required)
-                  ? required.includes(name)
-                  : required === true,
-                () => [
-                  create("strong", {
-                    style: {
-                      fontSize: "var(--ifm-code-font-size)",
-                      color: "var(--openapi-required)",
-                    },
-                    children: " required",
+                  create("span", {
+                    className: "openapi-schema__name",
+                    children: ` ${schemaName}`,
                   }),
-                ]
-              ),
+                  guard(
+                    (Array.isArray(required)
+                      ? required.includes(name)
+                      : required === true) ||
+                      schema.deprecated ||
+                      nullable,
+                    () => [
+                      create("span", {
+                        className: "openapi-schema__divider",
+                      }),
+                    ]
+                  ),
+                  guard(nullable, () => [
+                    create("span", {
+                      className: "openapi-schema__nullable",
+                      children: "nullable",
+                    }),
+                  ]),
+                  guard(
+                    Array.isArray(required)
+                      ? required.includes(name)
+                      : required === true,
+                    () => [
+                      create("span", {
+                        className: "openapi-schema__required",
+                        children: "required",
+                      }),
+                    ]
+                  ),
+                  guard(schema.deprecated, () => [
+                    create("span", {
+                      className: "openapi-schema__deprecated",
+                      children: "deprecated",
+                    }),
+                  ]),
+                ],
+              }),
             ],
           }),
           create("div", {
@@ -390,7 +416,7 @@ function createDetailsNode(
                   children: createDescription(description),
                 })
               ),
-              createNodes(schema),
+              createNodes(schema, SCHEMA_TYPE),
             ],
           }),
         ],
@@ -409,13 +435,12 @@ function createAnyOneOfProperty(
   required: string[] | boolean,
   nullable: boolean | unknown
 ): any {
-  const type = schema.oneOf ? "oneOf" : "anyOf";
-  const children = schema[type] || [];
   return create("SchemaItem", {
     collapsible: true,
     className: "schemaItem",
     children: [
       createDetails({
+        className: "openapi-markdown__details",
         children: [
           createDetailsSummary({
             children: [
@@ -470,39 +495,7 @@ function createAnyOneOfProperty(
               ),
             ],
           }),
-          create("div", {
-            children: [
-              create("span", {
-                className: "badge badge--info",
-                children: type,
-              }),
-              create("SchemaTabs", {
-                children: children.map((property, index) => {
-                  const label = property.title ?? `MOD${index + 1}`;
-                  if (property.properties) {
-                    return create("TabItem", {
-                      label: label,
-                      value: `${index}-property`,
-                      children: [createNodes(property)],
-                    });
-                  }
-                  return create("TabItem", {
-                    label: label,
-                    value: `${index}-property`,
-                    children: [
-                      create("p", { children: label }),
-                      guard(schema.description, (description) =>
-                        create("div", {
-                          style: { marginTop: ".5rem", marginBottom: ".5rem" },
-                          children: createDescription(description),
-                        })
-                      ),
-                    ],
-                  });
-                }),
-              }),
-            ],
-          }),
+          createAnyOneOf(schema),
         ],
       }),
     ],
@@ -519,7 +512,7 @@ function createPropertyDiscriminator(
   schema: SchemaObject,
   discriminator: any,
   required: string[] | boolean
-) {
+): any {
   if (schema === undefined) {
     return undefined;
   }
@@ -528,26 +521,61 @@ function createPropertyDiscriminator(
     return undefined;
   }
 
-  return create("SchemaItem", {
-    name,
-    required: Array.isArray(required) ? required.includes(name) : required,
-    schemaName: schemaName,
-    qualifierMessage: getQualifierMessage(schema),
-    schema: schema,
-    collapsible: false,
-    discriminator: true,
-    children: [
-      create("DiscriminatorTabs", {
-        children: Object.keys(discriminator?.mapping!).map((key, index) => {
-          const label = key;
-          return create("TabItem", {
-            label: label,
-            value: `${index}-item-discriminator`,
-            children: createNodes(discriminator?.mapping[key]),
-          });
+  return create("div", {
+    className: "openapi-discriminator__item openapi-schema__list-item",
+    children: create("div", {
+      children: [
+        create("span", {
+          className: "openapi-schema__container",
+          children: [
+            create("strong", {
+              className: "openapi-discriminator__name openapi-schema__property",
+              children: name,
+            }),
+            guard(schemaName, (name) =>
+              create("span", {
+                className: "openapi-schema__name",
+                children: ` ${schemaName}`,
+              })
+            ),
+            guard(required, () => [
+              create("span", {
+                className: "openapi-schema__required",
+                children: "required",
+              }),
+            ]),
+          ],
         }),
-      }),
-    ],
+        guard(getQualifierMessage(discriminator), (message) =>
+          create("div", {
+            style: {
+              paddingLeft: "1rem",
+            },
+            children: createDescription(message),
+          })
+        ),
+        guard(schema.description, (description) =>
+          create("div", {
+            style: {
+              paddingLeft: "1rem",
+            },
+            children: createDescription(description),
+          })
+        ),
+        create("DiscriminatorTabs", {
+          className: "openapi-tabs__discriminator",
+          children: Object.keys(discriminator?.mapping!).map((key, index) => {
+            const label = key;
+            return create("TabItem", {
+              // className: "openapi-tabs__discriminator-item",
+              label: label,
+              value: `${index}-item-discriminator`,
+              children: [createNodes(discriminator?.mapping[key], SCHEMA_TYPE)],
+            });
+          }),
+        }),
+      ],
+    }),
   });
 }
 
@@ -641,8 +669,16 @@ 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", {
@@ -696,8 +732,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
@@ -714,7 +758,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);

package/src/markdown/createStatusCodes.ts

@@ -266,45 +266,48 @@ export function createStatusCodes({ responses }: Props) {
 
   return create("div", {
     children: [
-      create("ApiTabs", {
-        // TODO: determine if we should persist status code selection
-        // groupId: "api-tabs",
-        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({
-                  "data-collaposed": true,
-                  open: false,
-                  style: { textAlign: "left", marginBottom: "1rem" },
-                  children: [
-                    createDetailsSummary({
+      create("div", {
+        children: [
+          create("ApiTabs", {
+            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-collaposed": true,
+                      open: false,
+                      style: { textAlign: "left", marginBottom: "1rem" },
                       children: [
-                        create("strong", {
-                          children: "Response Headers",
+                        createDetailsSummary({
+                          children: [
+                            create("strong", {
+                              children: "Response Headers",
+                            }),
+                          ],
                         }),
+                        createResponseHeaders(responseHeaders),
                       ],
                     }),
-                    createResponseHeaders(responseHeaders),
-                  ],
-                }),
-              create("div", {
-                children: createResponseSchema({
-                  title: "Schema",
-                  body: {
-                    content: responses[code].content,
-                  },
-                }),
-              }),
-            ],
-          });
-        }),
+                  create("div", {
+                    children: createResponseSchema({
+                      title: "Schema",
+                      body: {
+                        content: responses[code].content,
+                      },
+                    }),
+                  }),
+                ],
+              });
+            }),
+          }),
+        ],
       }),
     ],
   });