docusaurus-plugin-openapi-docs 1.1.4 → 1.1.5

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

@@ -227,8 +227,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 +391,7 @@ function createDetailsNode(
   name: string,
   schemaName: string,
   schema: SchemaObject,
-  required: any
+  required: string[] | boolean
 ): any {
   return create("SchemaItem", {
     collapsible: true,
@@ -402,7 +406,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 +450,7 @@ function createPropertyDiscriminator(
   schemaName: string,
   schema: SchemaObject,
   discriminator: any,
-  required: any
+  required: string[] | boolean
 ): any {
   if (schema === undefined) {
     return undefined;
@@ -515,7 +519,7 @@ function createPropertyDiscriminator(
 interface EdgeProps {
   name: string;
   schema: SchemaObject;
-  required: boolean;
+  required: string[] | boolean;
   discriminator?: any | unknown;
 }
 
@@ -530,6 +534,8 @@ function createEdges({
 }: EdgeProps): any {
   const schemaName = getSchemaName(schema);
 
+  // if (name === "id") console.log(name, schema, required);
+
   if (discriminator !== undefined && discriminator.propertyName === name) {
     return createPropertyDiscriminator(
       name,
@@ -548,9 +554,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 +578,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 +606,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),
@@ -685,11 +698,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,8 +712,75 @@ export function createSchemaDetails({ title, body, ...rest }: Props) {
     return undefined;
   }
 
-  // NOTE: We just pick a random content-type.
-  // How common is it to have multiple?
+  // Get all MIME types, including vendor-specific
+  const mimeTypes = Object.keys(body.content);
+
+  if (mimeTypes && mimeTypes.length > 1) {
+    return create("MimeTabs", {
+      groupId: "mime-type",
+      children: mimeTypes.map((mimeType) => {
+        const firstBody = body.content![mimeType].schema;
+        if (firstBody === undefined) {
+          return undefined;
+        }
+        if (firstBody.properties !== undefined) {
+          if (Object.keys(firstBody.properties).length === 0) {
+            return undefined;
+          }
+        }
+        return create("TabItem", {
+          label: mimeType,
+          value: `${mimeType}`,
+          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),
+                }),
+              ],
+            }),
+          ],
+        });
+      }),
+    });
+  }
+
   const randomFirstKey = Object.keys(body.content)[0];
   const firstBody = body.content[randomFirstKey].schema;
 
@@ -714,49 +794,57 @@ export function createSchemaDetails({ title, body, ...rest }: Props) {
       return undefined;
     }
   }
-
-  // Root-level schema dropdown
-  return createDetails({
-    "data-collapsed": false,
-    open: true,
-    ...rest,
+  return create("MimeTabs", {
     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" },
+      create("TabItem", {
+        label: randomFirstKey,
+        value: `${randomFirstKey}-schema`,
         children: [
-          guard(body.description, () => [
-            create("div", {
-              style: { marginTop: "1rem", marginBottom: "1rem" },
-              children: createDescription(body.description),
-            }),
-          ]),
+          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),
+                    }),
+                  ]),
+                ],
+              }),
+              create("ul", {
+                style: { marginLeft: "1rem" },
+                children: createNodes(firstBody),
+              }),
+            ],
+          }),
         ],
       }),
-      create("ul", {
-        style: { marginLeft: "1rem" },
-        children: createNodes(firstBody),
-      }),
     ],
   });
 }

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";
 
@@ -79,7 +79,11 @@ function createResponseExamples(responseExamples: any) {
         value: `${finalFormattedName}`,
         children: [
           create("ResponseSamples", {
-            responseExample: JSON.stringify(exampleValue.value, null, 2),
+            responseExample: JSON.stringify(
+              exampleValue.value ?? exampleValue,
+              null,
+              2
+            ),
           }),
         ],
       });
@@ -106,7 +110,9 @@ export function createStatusCodes({ responses }: Props) {
           const responseContentKey: any =
             responseContent && Object.keys(responseContent)[0];
           const responseExamples: any =
-            responseContentKey && responseContent[responseContentKey].examples;
+            responseContentKey &&
+            (responseContent[responseContentKey].examples ||
+              responseContent[responseContentKey].example);
 
           return create("TabItem", {
             label: code,
@@ -126,7 +132,7 @@ export function createStatusCodes({ responses }: Props) {
                           createDetails({
                             "data-collaposed": false,
                             open: true,
-                            style: { textAlign: "left" },
+                            style: { textAlign: "left", marginBottom: "1rem" },
                             children: [
                               createDetailsSummary({
                                 children: [
@@ -139,7 +145,7 @@ export function createStatusCodes({ responses }: Props) {
                             ],
                           }),
                         create("div", {
-                          children: createSchemaDetails({
+                          children: createResponseSchema({
                             title: "Schema",
                             body: {
                               content: responses[code].content,
@@ -152,7 +158,7 @@ export function createStatusCodes({ responses }: Props) {
                   ],
                 })
               ),
-              guard(responseHeaders, () =>
+              guard(responseHeaders && !responseExamples, () =>
                 createDetails({
                   "data-collaposed": false,
                   open: true,
@@ -169,7 +175,7 @@ export function createStatusCodes({ responses }: Props) {
               ),
               guard(!responseExamples, () =>
                 create("div", {
-                  children: createSchemaDetails({
+                  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;

package/src/sidebars/index.ts

@@ -37,7 +37,7 @@ function groupByTags(
   items: ApiPageMetadata[],
   sidebarOptions: SidebarOptions,
   options: APIOptions,
-  tags: TagObject[],
+  tags: TagObject[][],
   docPath: string
 ): ProcessedSidebar {
   const { outputDir, label } = options;
@@ -60,12 +60,20 @@ function groupByTags(
   });
 
   // TODO: make sure we only take the first tag
-  const apiTags = uniq(
+  const operationTags = uniq(
     apiItems
       .flatMap((item) => item.api.tags)
       .filter((item): item is string => !!item)
   );
 
+  // Only include operation tags that are globally defined
+  const apiTags: string[] = [];
+  tags.flat().forEach((tag) => {
+    if (operationTags.includes(tag.name!)) {
+      apiTags.push(tag.name!);
+    }
+  });
+
   const basePath = docPath
     ? outputDir.split(docPath!)[1].replace(/^\/+/g, "")
     : outputDir.slice(outputDir.indexOf("/", 1)).replace(/^\/+/g, "");
@@ -107,7 +115,7 @@ function groupByTags(
       );
       const tagObject = tags.flat().find(
         (t) =>
-          (tag === t.name || tag === t["x-displayName"]) ?? {
+          tag === t.name ?? {
             name: tag,
             description: `${tag} Index`,
           }
@@ -148,7 +156,7 @@ function groupByTags(
 
       return {
         type: "category" as const,
-        label: tag,
+        label: tagObject?.["x-displayName"] ?? tag,
         link: linkConfig,
         collapsible: sidebarCollapsible,
         collapsed: sidebarCollapsed,
@@ -191,7 +199,7 @@ export default function generateSidebarSlice(
   sidebarOptions: SidebarOptions,
   options: APIOptions,
   api: ApiMetadata[],
-  tags: TagObject[],
+  tags: TagObject[][],
   docPath: string
 ) {
   let sidebarSlice: ProcessedSidebar = [];