docusaurus-plugin-openapi-docs 1.1.2 → 1.1.5

package/src/markdown/createStatusCodes.ts

@@ -7,13 +7,90 @@
 
 import { ApiItem } from "../types";
 import { createDescription } from "./createDescription";
-import { createSchemaDetails } from "./createSchemaDetails";
+import { createDetails } from "./createDetails";
+import { createDetailsSummary } from "./createDetailsSummary";
+import { createResponseSchema } from "./createResponseSchema";
 import { create } from "./utils";
+import { guard } from "./utils";
 
 interface Props {
   responses: ApiItem["responses"];
 }
 
+function createResponseHeaders(responseHeaders: any) {
+  return guard(responseHeaders, () =>
+    create("ul", {
+      style: { marginLeft: "1rem" },
+      children: [
+        Object.entries(responseHeaders).map(([headerName, headerObj]) => {
+          const {
+            description,
+            schema: { type },
+            example,
+          }: any = headerObj;
+
+          return create("li", {
+            class: "schemaItem",
+            children: [
+              createDetailsSummary({
+                children: [
+                  create("strong", { children: headerName }),
+                  guard(type, () => [
+                    create("span", {
+                      style: { opacity: "0.6" },
+                      children: ` ${type}`,
+                    }),
+                  ]),
+                ],
+              }),
+              create("div", {
+                children: [
+                  guard(description, (description) =>
+                    create("div", {
+                      style: {
+                        marginTop: ".5rem",
+                        marginBottom: ".5rem",
+                      },
+                      children: [
+                        guard(example, () => `Example: ${example}`),
+                        createDescription(description),
+                      ],
+                    })
+                  ),
+                ],
+              }),
+            ],
+          });
+        }),
+      ],
+    })
+  );
+}
+
+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);
+
+      return create("TabItem", {
+        label: `${finalFormattedName}`,
+        value: `${finalFormattedName}`,
+        children: [
+          create("ResponseSamples", {
+            responseExample: JSON.stringify(
+              exampleValue.value ?? exampleValue,
+              null,
+              2
+            ),
+          }),
+        ],
+      });
+    }
+  );
+}
+
 export function createStatusCodes({ responses }: Props) {
   if (responses === undefined) {
     return undefined;
@@ -28,6 +105,15 @@ export function createStatusCodes({ responses }: Props) {
     children: [
       create("ApiTabs", {
         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 ||
+              responseContent[responseContentKey].example);
+
           return create("TabItem", {
             label: code,
             value: code,
@@ -35,14 +121,68 @@ export function createStatusCodes({ responses }: Props) {
               create("div", {
                 children: createDescription(responses[code].description),
               }),
-              create("div", {
-                children: createSchemaDetails({
-                  title: "Schema",
-                  body: {
-                    content: responses[code].content,
-                  },
-                }),
-              }),
+              guard(responseExamples, () =>
+                create("SchemaTabs", {
+                  children: [
+                    create("TabTtem", {
+                      label: "Schema",
+                      value: "Schema",
+                      children: [
+                        responseHeaders &&
+                          createDetails({
+                            "data-collaposed": false,
+                            open: true,
+                            style: { textAlign: "left", marginBottom: "1rem" },
+                            children: [
+                              createDetailsSummary({
+                                children: [
+                                  create("strong", {
+                                    children: "Response Headers",
+                                  }),
+                                ],
+                              }),
+                              createResponseHeaders(responseHeaders),
+                            ],
+                          }),
+                        create("div", {
+                          children: createResponseSchema({
+                            title: "Schema",
+                            body: {
+                              content: responses[code].content,
+                            },
+                          }),
+                        }),
+                      ],
+                    }),
+                    createResponseExamples(responseExamples),
+                  ],
+                })
+              ),
+              guard(responseHeaders && !responseExamples, () =>
+                createDetails({
+                  "data-collaposed": false,
+                  open: true,
+                  style: { textAlign: "left" },
+                  children: [
+                    createDetailsSummary({
+                      children: [
+                        create("strong", { children: "Response Headers" }),
+                      ],
+                    }),
+                    createResponseHeaders(responseHeaders),
+                  ],
+                })
+              ),
+              guard(!responseExamples, () =>
+                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";
@@ -18,6 +19,7 @@ import { createContactInfo } from "./createContactInfo";
 import { createDeprecationNotice } from "./createDeprecationNotice";
 import { createDescription } from "./createDescription";
 import { createLicense } from "./createLicense";
+import { createLogo } from "./createLogo";
 import { createParamsDetails } from "./createParamsDetails";
 import { createRequestBodyDetails } from "./createRequestBodyDetails";
 import { createStatusCodes } from "./createStatusCodes";
@@ -25,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: {
@@ -37,10 +50,13 @@ 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`,
-    `import ApiTabs from "@theme/ApiTabs";\n`,
     `import SchemaTabs from "@theme/SchemaTabs";\n`,
+    `import DiscriminatorTabs from "@theme/DiscriminatorTabs";\n`,
     `import TabItem from "@theme/TabItem";\n\n`,
     `## ${escape(title)}\n\n`,
     createDeprecationNotice({ deprecated, description: deprecatedDescription }),
@@ -49,20 +65,35 @@ 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 }),
   ]);
 }
 
 export function createInfoPageMD({
-  info: { title, version, description, contact, license, termsOfService },
+  info: {
+    title,
+    version,
+    description,
+    contact,
+    license,
+    termsOfService,
+    logo,
+    darkLogo,
+  },
   securitySchemes,
 }: InfoPageMetadata) {
   return render([
+    `import ApiLogo from "@theme/ApiLogo";\n`,
     `import Tabs from "@theme/Tabs";\n`,
     `import TabItem from "@theme/TabItem";\n\n`,
+
     createVersionBadge(version),
     `# ${escape(title)}\n\n`,
+    createLogo(logo, darkLogo),
     createDescription(description),
     createAuthentication(securitySchemes as unknown as SecuritySchemeObject),
     createContactInfo(contact as ContactObject),

package/src/markdown/schema.test.ts

@@ -17,19 +17,19 @@ describe("getQualifierMessage", () => {
   // minLength + maxLength
   //
   it("should render minLength", () => {
-    const expected = "**Possible values:** 1 ≤ length";
+    const expected = "**Possible values:** `non-empty`";
     const actual = getQualifierMessage({ minLength: 1 });
     expect(actual).toBe(expected);
   });
 
   it("should render maxLength", () => {
-    const expected = "**Possible values:** length ≤ 40";
+    const expected = "**Possible values:** `<= 40 characters`";
     const actual = getQualifierMessage({ maxLength: 40 });
     expect(actual).toBe(expected);
   });
 
   it("should render minLength and maxLength", () => {
-    const expected = "**Possible values:** 1 ≤ length ≤ 40";
+    const expected = "**Possible values:** `non-empty` and `<= 40 characters`";
     const actual = getQualifierMessage({ minLength: 1, maxLength: 40 });
     expect(actual).toBe(expected);
   });
@@ -46,7 +46,7 @@ describe("getQualifierMessage", () => {
 
   it("should render multiple string qualifiers", () => {
     const expected =
-      "**Possible values:** 1 ≤ length ≤ 40, Value must match regular expression `^[a-zA-Z0-9_-]*$`";
+      "**Possible values:** `non-empty` and `<= 40 characters`, Value must match regular expression `^[a-zA-Z0-9_-]*$`";
     const actual = getQualifierMessage({
       minLength: 1,
       maxLength: 40,
@@ -68,49 +68,49 @@ describe("getQualifierMessage", () => {
   // minimum + maximum + exclusiveMinimum + exclusiveMaximum
   //
   it("should render minimum", () => {
-    const expected = "**Possible values:** 1 ≤ value";
+    const expected = "**Possible values:** `>= 1`";
     const actual = getQualifierMessage({ minimum: 1 });
     expect(actual).toBe(expected);
   });
 
   it("should render maximum", () => {
-    const expected = "**Possible values:** value ≤ 40";
+    const expected = "**Possible values:** `<= 40`";
     const actual = getQualifierMessage({ maximum: 40 });
     expect(actual).toBe(expected);
   });
 
   it("should render numeric exclusiveMinimum", () => {
-    const expected = "**Possible values:** 1 < value";
+    const expected = "**Possible values:** `> 1`";
     const actual = getQualifierMessage({ exclusiveMinimum: 1 });
     expect(actual).toBe(expected);
   });
 
   it("should render numeric exclusiveMaximum", () => {
-    const expected = "**Possible values:** value < 40";
+    const expected = "**Possible values:** `< 40`";
     const actual = getQualifierMessage({ exclusiveMaximum: 40 });
     expect(actual).toBe(expected);
   });
 
   it("should render boolean exclusiveMinimum", () => {
-    const expected = "**Possible values:** 1 < value";
+    const expected = "**Possible values:** `> 1`";
     const actual = getQualifierMessage({ minimum: 1, exclusiveMinimum: true });
     expect(actual).toBe(expected);
   });
 
   it("should render boolean exclusiveMaximum", () => {
-    const expected = "**Possible values:** value < 40";
+    const expected = "**Possible values:** `< 40`";
     const actual = getQualifierMessage({ maximum: 40, exclusiveMaximum: true });
     expect(actual).toBe(expected);
   });
 
   it("should render minimum when exclusiveMinimum is false", () => {
-    const expected = "**Possible values:** 1 ≤ value";
+    const expected = "**Possible values:** `>= 1`";
     const actual = getQualifierMessage({ minimum: 1, exclusiveMinimum: false });
     expect(actual).toBe(expected);
   });
 
   it("should render maximum when exclusiveMaximum is false", () => {
-    const expected = "**Possible values:** value ≤ 40";
+    const expected = "**Possible values:** `<= 40`";
     const actual = getQualifierMessage({
       maximum: 40,
       exclusiveMaximum: false,
@@ -119,13 +119,13 @@ describe("getQualifierMessage", () => {
   });
 
   it("should render minimum and maximum", () => {
-    const expected = "**Possible values:** 1 ≤ value ≤ 40";
+    const expected = "**Possible values:** `>= 1` and `<= 40`";
     const actual = getQualifierMessage({ minimum: 1, maximum: 40 });
     expect(actual).toBe(expected);
   });
 
   it("should render boolean exclusiveMinimum and maximum", () => {
-    const expected = "**Possible values:** 1 < value ≤ 40";
+    const expected = "**Possible values:** `> 1` and `<= 40`";
     const actual = getQualifierMessage({
       minimum: 1,
       maximum: 40,
@@ -135,7 +135,7 @@ describe("getQualifierMessage", () => {
   });
 
   it("should render minimum and boolean exclusiveMaximum", () => {
-    const expected = "**Possible values:** 1 ≤ value < 40";
+    const expected = "**Possible values:** `>= 1` and `< 40`";
     const actual = getQualifierMessage({
       minimum: 1,
       maximum: 40,
@@ -145,7 +145,7 @@ describe("getQualifierMessage", () => {
   });
 
   it("should render numeric exclusiveMinimum and maximum", () => {
-    const expected = "**Possible values:** 1 < value ≤ 40";
+    const expected = "**Possible values:** `> 1` and `<= 40`";
     const actual = getQualifierMessage({
       exclusiveMinimum: 1,
       maximum: 40,
@@ -154,7 +154,7 @@ describe("getQualifierMessage", () => {
   });
 
   it("should render minimum and numeric exclusiveMaximum", () => {
-    const expected = "**Possible values:** 1 ≤ value < 40";
+    const expected = "**Possible values:** `>= 1` and `< 40`";
     const actual = getQualifierMessage({
       minimum: 1,
       exclusiveMaximum: 40,
@@ -163,7 +163,7 @@ describe("getQualifierMessage", () => {
   });
 
   it("should render numeric exclusiveMinimum and boolean exclusiveMaximum", () => {
-    const expected = "**Possible values:** 1 < value < 40";
+    const expected = "**Possible values:** `> 1` and `< 40`";
     const actual = getQualifierMessage({
       exclusiveMinimum: 1,
       maximum: 40,

package/src/markdown/schema.ts

@@ -64,7 +64,11 @@ export function getQualifierMessage(schema?: SchemaObject): string | undefined {
     return undefined;
   }
 
-  if (schema.items) {
+  if (
+    schema.items &&
+    schema.minItems === undefined &&
+    schema.maxItems === undefined
+  ) {
     return getQualifierMessage(schema.items);
   }
 
@@ -72,15 +76,38 @@ export function getQualifierMessage(schema?: SchemaObject): string | undefined {
 
   let qualifierGroups = [];
 
+  if (schema.items && schema.items.enum) {
+    if (schema.items.enum) {
+      qualifierGroups.push(
+        `[${schema.items.enum.map((e) => `\`${e}\``).join(", ")}]`
+      );
+    }
+  }
+
   if (schema.minLength || schema.maxLength) {
     let lengthQualifier = "";
-    if (schema.minLength) {
-      lengthQualifier += `${schema.minLength} ≤ `;
+    let minLength;
+    let maxLength;
+    if (schema.minLength && schema.minLength > 1) {
+      minLength = `\`>= ${schema.minLength} characters\``;
+    }
+    if (schema.minLength && schema.minLength === 1) {
+      minLength = `\`non-empty\``;
     }
-    lengthQualifier += "length";
     if (schema.maxLength) {
-      lengthQualifier += ` ≤ ${schema.maxLength}`;
+      maxLength = `\`<= ${schema.maxLength} characters\``;
+    }
+
+    if (minLength && !maxLength) {
+      lengthQualifier += minLength;
+    }
+    if (maxLength && !minLength) {
+      lengthQualifier += maxLength;
     }
+    if (minLength && maxLength) {
+      lengthQualifier += `${minLength} and ${maxLength}`;
+    }
+
     qualifierGroups.push(lengthQualifier);
   }
 
@@ -91,21 +118,33 @@ export function getQualifierMessage(schema?: SchemaObject): string | undefined {
     typeof schema.exclusiveMaximum === "number"
   ) {
     let minmaxQualifier = "";
+    let minimum;
+    let maximum;
     if (typeof schema.exclusiveMinimum === "number") {
-      minmaxQualifier += `${schema.exclusiveMinimum} < `;
+      minimum = `\`> ${schema.exclusiveMinimum}\``;
     } else if (schema.minimum && !schema.exclusiveMinimum) {
-      minmaxQualifier += `${schema.minimum} ≤ `;
+      minimum = `\`>= ${schema.minimum}\``;
     } else if (schema.minimum && schema.exclusiveMinimum === true) {
-      minmaxQualifier += `${schema.minimum} < `;
+      minimum = `\`> ${schema.minimum}\``;
     }
-    minmaxQualifier += "value";
     if (typeof schema.exclusiveMaximum === "number") {
-      minmaxQualifier += ` < ${schema.exclusiveMaximum}`;
+      maximum = `\`< ${schema.exclusiveMaximum}\``;
     } else if (schema.maximum && !schema.exclusiveMaximum) {
-      minmaxQualifier += ` ≤ ${schema.maximum}`;
+      maximum = `\`<= ${schema.maximum}\``;
     } else if (schema.maximum && schema.exclusiveMaximum === true) {
-      minmaxQualifier += ` < ${schema.maximum}`;
+      maximum = `\`< ${schema.maximum}\``;
+    }
+
+    if (minimum && !maximum) {
+      minmaxQualifier += minimum;
+    }
+    if (maximum && !minimum) {
+      minmaxQualifier += maximum;
     }
+    if (minimum && maximum) {
+      minmaxQualifier += `${minimum} and ${maximum}`;
+    }
+
     qualifierGroups.push(minmaxQualifier);
   }
 
@@ -115,16 +154,23 @@ export function getQualifierMessage(schema?: SchemaObject): string | undefined {
     );
   }
 
+  // Check if discriminator mapping
+  const discriminator = schema as any;
+  if (discriminator.mapping) {
+    const values = Object.keys(discriminator.mapping);
+    qualifierGroups.push(`[${values.map((e) => `\`${e}\``).join(", ")}]`);
+  }
+
   if (schema.enum) {
     qualifierGroups.push(`[${schema.enum.map((e) => `\`${e}\``).join(", ")}]`);
   }
 
   if (schema.minItems) {
-    qualifierGroups.push(`items >= ${schema.minItems}`);
+    qualifierGroups.push(`\`>= ${schema.minItems}\``);
   }
 
   if (schema.maxItems) {
-    qualifierGroups.push(`items <= ${schema.maxItems}`);
+    qualifierGroups.push(`\`<= ${schema.maxItems}\``);
   }
 
   if (qualifierGroups.length === 0) {

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;