docusaurus-plugin-openapi-docs 1.1.4 → 1.1.7

package/src/markdown/{createSchemaDetails.ts → createResponseSchema.ts}

@@ -9,6 +9,10 @@ import { MediaTypeObject, SchemaObject } from "../openapi/types";
 import { createDescription } from "./createDescription";
 import { createDetails } from "./createDetails";
 import { createDetailsSummary } from "./createDetailsSummary";
+import {
+  createResponseExample,
+  createResponseExamples,
+} from "./createStatusCodes";
 import { getQualifierMessage, getSchemaName } from "./schema";
 import { create, guard } from "./utils";
 
@@ -227,8 +231,12 @@ function createItems(schema: SchemaObject) {
   }
 
   if (schema.items?.allOf !== undefined) {
-    const { mergedSchemas }: { mergedSchemas: SchemaObject; required: any } =
-      mergeAllOf(schema.items?.allOf);
+    // TODO: figure out if and how we should pass merged required array
+    const {
+      mergedSchemas,
+    }: { mergedSchemas: SchemaObject; required: string[] } = mergeAllOf(
+      schema.items?.allOf
+    );
 
     // Handles combo anyOf/oneOf + properties
     if (
@@ -387,7 +395,7 @@ function createDetailsNode(
   name: string,
   schemaName: string,
   schema: SchemaObject,
-  required: any
+  required: string[] | boolean
 ): any {
   return create("SchemaItem", {
     collapsible: true,
@@ -402,7 +410,7 @@ function createDetailsNode(
                 style: { opacity: "0.6" },
                 children: ` ${schemaName}`,
               }),
-              guard(required, () => [
+              guard(schema.required && schema.required === true, () => [
                 create("strong", {
                   style: {
                     fontSize: "var(--ifm-code-font-size)",
@@ -446,7 +454,7 @@ function createPropertyDiscriminator(
   schemaName: string,
   schema: SchemaObject,
   discriminator: any,
-  required: any
+  required: string[] | boolean
 ): any {
   if (schema === undefined) {
     return undefined;
@@ -515,7 +523,7 @@ function createPropertyDiscriminator(
 interface EdgeProps {
   name: string;
   schema: SchemaObject;
-  required: boolean;
+  required: string[] | boolean;
   discriminator?: any | unknown;
 }
 
@@ -548,9 +556,8 @@ function createEdges({
     const {
       mergedSchemas,
       required,
-    }: { mergedSchemas: SchemaObject; required: any } = mergeAllOf(
-      schema.allOf
-    );
+    }: { mergedSchemas: SchemaObject; required: string[] | boolean } =
+      mergeAllOf(schema.allOf);
     const mergedSchemaName = getSchemaName(mergedSchemas);
 
     if (
@@ -573,14 +580,18 @@ function createEdges({
       return createDetailsNode(name, mergedSchemaName, mergedSchemas, required);
     }
 
+    if (mergedSchemas.writeOnly && mergedSchemas.writeOnly === true) {
+      return undefined;
+    }
+
     return create("SchemaItem", {
       collapsible: false,
       name,
-      required,
+      required: false,
       schemaDescription: mergedSchemas.description,
       schemaName: schemaName,
       qualifierMessage: getQualifierMessage(schema),
-      defaultValue: schema.default,
+      defaultValue: mergedSchemas.default,
     });
   }
 
@@ -597,11 +608,15 @@ function createEdges({
     return createDetailsNode(name, schemaName, schema, required);
   }
 
+  if (schema.writeOnly && schema.writeOnly === true) {
+    return undefined;
+  }
+
   // primitives and array of non-objects
   return create("SchemaItem", {
     collapsible: false,
     name,
-    required,
+    required: false,
     schemaDescription: schema.description,
     schemaName: schemaName,
     qualifierMessage: getQualifierMessage(schema),
@@ -634,7 +649,8 @@ function createNodes(schema: SchemaObject): any {
     return createProperties(schema);
   }
 
-  if (schema.additionalProperties !== undefined) {
+  // Could be set to false to just check if evals to true
+  if (schema.additionalProperties) {
     return createAdditionalProperties(schema);
   }
 
@@ -685,11 +701,11 @@ interface Props {
       [key: string]: MediaTypeObject;
     };
     description?: string;
-    required?: boolean;
+    required?: string[] | boolean;
   };
 }
 
-export function createSchemaDetails({ title, body, ...rest }: Props) {
+export function createResponseSchema({ title, body, ...rest }: Props) {
   if (
     body === undefined ||
     body.content === undefined ||
@@ -699,64 +715,103 @@ export function createSchemaDetails({ title, body, ...rest }: Props) {
     return undefined;
   }
 
-  // NOTE: We just pick a random content-type.
-  // How common is it to have multiple?
-  const randomFirstKey = Object.keys(body.content)[0];
-  const firstBody = body.content[randomFirstKey].schema;
-
-  if (firstBody === undefined) {
-    return undefined;
-  }
-
-  // we don't show the table if there is no properties to show
-  if (firstBody.properties !== undefined) {
-    if (Object.keys(firstBody.properties).length === 0) {
-      return undefined;
-    }
-  }
-
-  // Root-level schema dropdown
-  return createDetails({
-    "data-collapsed": false,
-    open: true,
-    ...rest,
-    children: [
-      createDetailsSummary({
-        style: { textAlign: "left" },
-        children: [
-          create("strong", { children: `${title}` }),
-          guard(firstBody.type === "array", (format) =>
-            create("span", {
-              style: { opacity: "0.6" },
-              children: ` array`,
-            })
-          ),
-          guard(body.required, () => [
-            create("strong", {
-              style: {
-                fontSize: "var(--ifm-code-font-size)",
-                color: "var(--openapi-required)",
-              },
-              children: " required",
-            }),
-          ]),
-        ],
-      }),
-      create("div", {
-        style: { textAlign: "left", marginLeft: "1rem" },
-        children: [
-          guard(body.description, () => [
-            create("div", {
-              style: { marginTop: "1rem", marginBottom: "1rem" },
-              children: createDescription(body.description),
+  // Get all MIME types, including vendor-specific
+  const mimeTypes = Object.keys(body.content);
+
+  if (mimeTypes && mimeTypes.length) {
+    return create("MimeTabs", {
+      groupId: "mime-type",
+      children: mimeTypes.map((mimeType: any) => {
+        const responseExamples = body.content![mimeType].examples;
+        const responseExample = body.content![mimeType].example;
+        const firstBody = body.content![mimeType].schema;
+
+        if (
+          firstBody === undefined &&
+          responseExample === undefined &&
+          responseExamples === undefined
+        ) {
+          return undefined;
+        }
+
+        if (firstBody?.properties !== undefined) {
+          if (Object.keys(firstBody?.properties).length === 0) {
+            return undefined;
+          }
+        }
+
+        return create("TabItem", {
+          label: `${mimeType}`,
+          value: `${mimeType}`,
+          children: [
+            create("SchemaTabs", {
+              groupId: "schema-tabs",
+              children: [
+                firstBody &&
+                  create("TabTtem", {
+                    label: `${title}`,
+                    value: `${title}`,
+                    children: [
+                      createDetails({
+                        "data-collapsed": false,
+                        open: true,
+                        ...rest,
+                        children: [
+                          createDetailsSummary({
+                            style: { textAlign: "left" },
+                            children: [
+                              create("strong", { children: `${title}` }),
+                              guard(firstBody!.type === "array", (format) =>
+                                create("span", {
+                                  style: { opacity: "0.6" },
+                                  children: ` array`,
+                                })
+                              ),
+                              guard(
+                                body.required && body.required === true,
+                                () => [
+                                  create("strong", {
+                                    style: {
+                                      fontSize: "var(--ifm-code-font-size)",
+                                      color: "var(--openapi-required)",
+                                    },
+                                    children: " required",
+                                  }),
+                                ]
+                              ),
+                            ],
+                          }),
+                          create("div", {
+                            style: { textAlign: "left", marginLeft: "1rem" },
+                            children: [
+                              guard(body.description, () => [
+                                create("div", {
+                                  style: {
+                                    marginTop: "1rem",
+                                    marginBottom: "1rem",
+                                  },
+                                  children: createDescription(body.description),
+                                }),
+                              ]),
+                            ],
+                          }),
+                          create("ul", {
+                            style: { marginLeft: "1rem" },
+                            children: createNodes(firstBody!),
+                          }),
+                        ],
+                      }),
+                    ],
+                  }),
+                responseExamples && createResponseExamples(responseExamples),
+                responseExample && createResponseExample(responseExample),
+              ],
             }),
-          ]),
-        ],
-      }),
-      create("ul", {
-        style: { marginLeft: "1rem" },
-        children: createNodes(firstBody),
+          ],
+        });
       }),
-    ],
-  });
+    });
+  }
+
+  return undefined;
 }

package/src/markdown/createStatusCodes.ts

@@ -9,7 +9,7 @@ import { ApiItem } from "../types";
 import { createDescription } from "./createDescription";
 import { createDetails } from "./createDetails";
 import { createDetailsSummary } from "./createDetailsSummary";
-import { createSchemaDetails } from "./createSchemaDetails";
+import { createResponseSchema } from "./createResponseSchema";
 import { create } from "./utils";
 import { guard } from "./utils";
 
@@ -67,19 +67,30 @@ function createResponseHeaders(responseHeaders: any) {
   );
 }
 
-function createResponseExamples(responseExamples: any) {
+export function createResponseExamples(responseExamples: any) {
   return Object.entries(responseExamples).map(
     ([exampleName, exampleValue]: any) => {
       const camelToSpaceName = exampleName.replace(/([A-Z])/g, " $1");
       let finalFormattedName =
         camelToSpaceName.charAt(0).toUpperCase() + camelToSpaceName.slice(1);
 
+      if (typeof exampleValue.value === "object") {
+        return create("TabItem", {
+          label: `${finalFormattedName}`,
+          value: `${finalFormattedName}`,
+          children: [
+            create("ResponseSamples", {
+              responseExample: JSON.stringify(exampleValue.value, null, 2),
+            }),
+          ],
+        });
+      }
       return create("TabItem", {
         label: `${finalFormattedName}`,
         value: `${finalFormattedName}`,
         children: [
           create("ResponseSamples", {
-            responseExample: JSON.stringify(exampleValue.value, null, 2),
+            responseExample: exampleValue.value,
           }),
         ],
       });
@@ -87,6 +98,29 @@ function createResponseExamples(responseExamples: any) {
   );
 }
 
+export function createResponseExample(responseExample: any) {
+  if (typeof responseExample === "object") {
+    return create("TabItem", {
+      label: `Example`,
+      value: `Example`,
+      children: [
+        create("ResponseSamples", {
+          responseExample: JSON.stringify(responseExample, null, 2),
+        }),
+      ],
+    });
+  }
+  return create("TabItem", {
+    label: `Example`,
+    value: `Example`,
+    children: [
+      create("ResponseSamples", {
+        responseExample: responseExample,
+      }),
+    ],
+  });
+}
+
 export function createStatusCodes({ responses }: Props) {
   if (responses === undefined) {
     return undefined;
@@ -100,14 +134,10 @@ 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;
-          const responseContent: any = responses[code].content;
-          const responseContentKey: any =
-            responseContent && Object.keys(responseContent)[0];
-          const responseExamples: any =
-            responseContentKey && responseContent[responseContentKey].examples;
-
           return create("TabItem", {
             label: code,
             value: code,
@@ -115,68 +145,30 @@ export function createStatusCodes({ responses }: Props) {
               create("div", {
                 children: createDescription(responses[code].description),
               }),
-              guard(responseExamples, () =>
-                create("SchemaTabs", {
-                  children: [
-                    create("TabTtem", {
-                      label: "Schema",
-                      value: "Schema",
-                      children: [
-                        responseHeaders &&
-                          createDetails({
-                            "data-collaposed": false,
-                            open: true,
-                            style: { textAlign: "left" },
-                            children: [
-                              createDetailsSummary({
-                                children: [
-                                  create("strong", {
-                                    children: "Response Headers",
-                                  }),
-                                ],
-                              }),
-                              createResponseHeaders(responseHeaders),
-                            ],
-                          }),
-                        create("div", {
-                          children: createSchemaDetails({
-                            title: "Schema",
-                            body: {
-                              content: responses[code].content,
-                            },
-                          }),
-                        }),
-                      ],
-                    }),
-                    createResponseExamples(responseExamples),
-                  ],
-                })
-              ),
-              guard(responseHeaders, () =>
+              responseHeaders &&
                 createDetails({
                   "data-collaposed": false,
                   open: true,
-                  style: { textAlign: "left" },
+                  style: { textAlign: "left", marginBottom: "1rem" },
                   children: [
                     createDetailsSummary({
                       children: [
-                        create("strong", { children: "Response Headers" }),
+                        create("strong", {
+                          children: "Response Headers",
+                        }),
                       ],
                     }),
                     createResponseHeaders(responseHeaders),
                   ],
-                })
-              ),
-              guard(!responseExamples, () =>
-                create("div", {
-                  children: createSchemaDetails({
-                    title: "Schema",
-                    body: {
-                      content: responses[code].content,
-                    },
-                  }),
-                })
-              ),
+                }),
+              create("div", {
+                children: createResponseSchema({
+                  title: "Schema",
+                  body: {
+                    content: responses[code].content,
+                  },
+                }),
+              }),
             ],
           });
         }),

package/src/markdown/index.ts

@@ -10,6 +10,7 @@ import { escape } from "lodash";
 import {
   ContactObject,
   LicenseObject,
+  MediaTypeObject,
   SecuritySchemeObject,
 } from "../openapi/types";
 import { ApiPageMetadata, InfoPageMetadata, TagPageMetadata } from "../types";
@@ -26,6 +27,17 @@ import { createTermsOfService } from "./createTermsOfService";
 import { createVersionBadge } from "./createVersionBadge";
 import { render } from "./utils";
 
+interface Props {
+  title: string;
+  body: {
+    content?: {
+      [key: string]: MediaTypeObject;
+    };
+    description?: string;
+    required?: boolean;
+  };
+}
+
 export function createApiPageMD({
   title,
   api: {
@@ -39,6 +51,7 @@ export function createApiPageMD({
 }: ApiPageMetadata) {
   return render([
     `import ApiTabs from "@theme/ApiTabs";\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`,
@@ -52,7 +65,10 @@ export function createApiPageMD({
     createParamsDetails({ parameters, type: "query" }),
     createParamsDetails({ parameters, type: "header" }),
     createParamsDetails({ parameters, type: "cookie" }),
-    createRequestBodyDetails({ title: "Request Body", body: requestBody }),
+    createRequestBodyDetails({
+      title: "Request Body",
+      body: requestBody,
+    } as Props),
     createStatusCodes({ responses }),
   ]);
 }

package/src/openapi/createExample.ts

@@ -7,6 +7,7 @@
 
 import chalk from "chalk";
 
+import { mergeAllOf } from "../markdown/createRequestSchema";
 import { SchemaObject } from "./types";
 
 interface OASTypeToTypeMap {
@@ -29,6 +30,7 @@ const primitives: Primitives = {
     default: () => "string",
     email: () => "user@example.com",
     date: () => new Date().toISOString().substring(0, 10),
+    "date-time": () => new Date().toISOString().substring(0, 10),
     uuid: () => "3fa85f64-5717-4562-b3fc-2c963f66afa6",
     hostname: () => "example.com",
     ipv4: () => "198.51.100.42",
@@ -58,21 +60,16 @@ export const sampleFromSchema = (schema: SchemaObject = {}): any => {
     }
 
     if (allOf) {
-      // TODO: We are just assuming it will always be an object for now
-      let obj: SchemaObject = {
-        type: "object",
-        properties: {},
-        required: [], // NOTE: We shouldn't need to worry about required
-      };
-      for (let item of allOf) {
-        if (item.properties) {
-          obj.properties = {
-            ...obj.properties,
-            ...item.properties,
-          };
+      const { mergedSchemas }: { mergedSchemas: SchemaObject } =
+        mergeAllOf(allOf);
+      if (mergedSchemas.properties) {
+        for (const [key, value] of Object.entries(mergedSchemas.properties)) {
+          if (value.readOnly && value.readOnly === true) {
+            delete mergedSchemas.properties[key];
+          }
         }
       }
-      return sampleFromSchema(obj);
+      return sampleFromSchema(mergedSchemas);
     }
 
     if (!type) {
@@ -88,6 +85,22 @@ export const sampleFromSchema = (schema: SchemaObject = {}): any => {
     if (type === "object") {
       let obj: any = {};
       for (let [name, prop] of Object.entries(properties ?? {})) {
+        if (prop.properties) {
+          for (const [key, value] of Object.entries(prop.properties)) {
+            if (value.readOnly && value.readOnly === true) {
+              delete prop.properties[key];
+            }
+          }
+        }
+
+        if (prop.items && prop.items.properties) {
+          for (const [key, value] of Object.entries(prop.items.properties)) {
+            if (value.readOnly && value.readOnly === true) {
+              delete prop.items.properties[key];
+            }
+          }
+        }
+
         if (prop.deprecated) {
           continue;
         }
@@ -115,6 +128,10 @@ export const sampleFromSchema = (schema: SchemaObject = {}): any => {
       return normalizeArray(schema.enum)[0];
     }
 
+    if (schema.readOnly && schema.readOnly === true) {
+      return undefined;
+    }
+
     return primitive(schema);
   } catch (err) {
     console.error(
@@ -131,7 +148,7 @@ function primitive(schema: SchemaObject = {}) {
     return;
   }
 
-  let fn = primitives[type].default;
+  let fn = schema.default ? () => schema.default : primitives[type].default;
 
   if (format !== undefined) {
     fn = primitives[type][format] || fn;

package/src/openapi/openapi.ts

@@ -124,9 +124,7 @@ function createItems(
       securitySchemes: openapiData.components?.securitySchemes,
       info: {
         ...openapiData.info,
-        tags: openapiData.tags?.map((tagName) =>
-          getTagDisplayName(tagName.name!, openapiData.tags ?? [])
-        ),
+        tags: openapiData.tags,
         title: openapiData.info.title ?? "Introduction",
         logo: openapiData.info["x-logo"]! as any,
         darkLogo: openapiData.info["x-dark-logo"]! as any,
@@ -175,6 +173,18 @@ function createItems(
         jsonRequestBodyExample = sampleFromSchema(body.schema);
       }
 
+      // Handle vendor JSON media types
+      const bodyContent = operationObject.requestBody?.content;
+      if (bodyContent) {
+        const firstBodyContentKey = Object.keys(bodyContent)[0];
+        if (firstBodyContentKey.endsWith("+json")) {
+          const firstBody = bodyContent[firstBodyContentKey];
+          if (firstBody?.schema) {
+            jsonRequestBodyExample = sampleFromSchema(firstBody.schema);
+          }
+        }
+      }
+
       // TODO: Don't include summary temporarilly
       const { summary, ...defaults } = operationObject;
 
@@ -188,9 +198,7 @@ function createItems(
         frontMatter: {},
         api: {
           ...defaults,
-          tags: operationObject.tags?.map((tagName) =>
-            getTagDisplayName(tagName, openapiData.tags ?? [])
-          ),
+          tags: operationObject.tags,
           method,
           path,
           servers,
@@ -291,7 +299,7 @@ export async function readOpenapiFiles(
 export async function processOpenapiFiles(
   files: OpenApiFiles[],
   sidebarOptions: SidebarOptions
-): Promise<[ApiMetadata[], TagObject[]]> {
+): Promise<[ApiMetadata[], TagObject[][]]> {
   const promises = files.map(async (file) => {
     if (file.data !== undefined) {
       const processedFile = await processOpenapiFile(file.data, sidebarOptions);
@@ -326,7 +334,7 @@ export async function processOpenapiFiles(
       // Remove undefined tags due to transient parsing errors
       return x !== undefined;
     });
-  return [items as ApiMetadata[], tags as TagObject[]];
+  return [items as ApiMetadata[], tags as TagObject[][]];
 }
 
 export async function processOpenapiFile(

package/src/openapi/types.ts

@@ -41,7 +41,7 @@ export interface InfoObject {
   contact?: ContactObject;
   license?: LicenseObject;
   version: string;
-  tags?: String[];
+  tags?: TagObject[];
   "x-logo"?: LogoObject;
   "x-dark-logo"?: LogoObject;
   logo?: LogoObject;