docusaurus-plugin-openapi-docs 4.7.0 → 5.0.0

package/src/markdown/createLicense.ts

@@ -10,7 +10,7 @@ import { LicenseObject } from "../openapi/types";
 
 export function createLicense(license: LicenseObject) {
   if (!license || !Object.keys(license).length) return "";
-  const { name, url } = license;
+  const { name, url, identifier } = license;
 
   return create("div", {
     style: {
@@ -29,6 +29,12 @@ export function createLicense(license: LicenseObject) {
           children: name ?? url,
         })
       ),
+      guard(identifier, () =>
+        create("a", {
+          href: `https://spdx.org/licenses/${identifier}.html`,
+          children: name ?? identifier,
+        })
+      ),
     ],
   });
 }

package/src/markdown/createSchema.ts

@@ -17,7 +17,7 @@ import {
 import { createDescription } from "./createDescription";
 import { createDetails } from "./createDetails";
 import { createDetailsSummary } from "./createDetailsSummary";
-import { getQualifierMessage, getSchemaName } from "./schema";
+import { getSchemaName } from "./schema";
 import { create, guard } from "./utils";
 import { SchemaObject } from "../openapi/types";
 
@@ -32,7 +32,7 @@ export function mergeAllOf(allOf: SchemaObject) {
   };
 
   const mergedSchemas = merge(allOf, { onMergeError }) as SchemaObject;
-  return mergedSchemas;
+  return mergedSchemas ?? ({} as SchemaObject);
 }
 
 /**
@@ -140,7 +140,6 @@ function createProperties(schema: SchemaObject) {
       name: "",
       required: false,
       schemaName: "object",
-      qualifierMessage: undefined,
       schema: {},
     });
   }
@@ -169,7 +168,6 @@ function createAdditionalProperties(schema: SchemaObject) {
       name: "property name*",
       required: false,
       schemaName: "any",
-      qualifierMessage: getQualifierMessage(schema),
       schema: schema,
       collapsible: false,
       discriminator: false,
@@ -209,7 +207,6 @@ function createAdditionalProperties(schema: SchemaObject) {
       name: "property name*",
       required: false,
       schemaName: schemaName,
-      qualifierMessage: getQualifierMessage(schema),
       schema: additionalProperties,
       collapsible: false,
       discriminator: false,
@@ -399,12 +396,6 @@ function createDetailsNode(
                   children: createDescription(description),
                 })
               ),
-              guard(getQualifierMessage(schema), (message) =>
-                create("div", {
-                  style: { marginTop: ".5rem", marginBottom: ".5rem" },
-                  children: createDescription(message),
-                })
-              ),
               createNodes(schema, SCHEMA_TYPE),
             ],
           }),
@@ -545,14 +536,6 @@ function createPropertyDiscriminator(
             children: createDescription(description),
           })
         ),
-        guard(getQualifierMessage(discriminator), (message) =>
-          create("div", {
-            style: {
-              paddingLeft: "1rem",
-            },
-            children: createDescription(message),
-          })
-        ),
         create("DiscriminatorTabs", {
           className: "openapi-tabs__discriminator",
           children: Object.keys(discriminator?.mapping!).map((key, index) => {
@@ -727,7 +710,6 @@ function createEdges({
       name,
       required: Array.isArray(required) ? required.includes(name) : required,
       schemaName: mergedSchemaName,
-      qualifierMessage: getQualifierMessage(mergedSchemas),
       schema: mergedSchemas,
     });
   }
@@ -738,7 +720,6 @@ function createEdges({
     name,
     required: Array.isArray(required) ? required.includes(name) : required,
     schemaName: schemaName,
-    qualifierMessage: getQualifierMessage(schema),
     schema: schema,
   });
 }
@@ -823,17 +804,7 @@ export function createNodes(
         marginTop: ".5rem",
         marginBottom: ".5rem",
       },
-      children: [
-        createDescription(schema.type),
-        guard(getQualifierMessage(schema), (message) =>
-          create("div", {
-            style: {
-              paddingTop: "1rem",
-            },
-            children: createDescription(message),
-          })
-        ),
-      ],
+      children: [createDescription(schema.type)],
     });
   }
 
@@ -844,17 +815,7 @@ export function createNodes(
         marginTop: ".5rem",
         marginBottom: ".5rem",
       },
-      children: [
-        createDescription(schema),
-        guard(getQualifierMessage(schema), (message) =>
-          create("div", {
-            style: {
-              paddingTop: "1rem",
-            },
-            children: createDescription(message),
-          })
-        ),
-      ],
+      children: [createDescription(schema)],
     });
   }
 

package/src/markdown/schema.ts

@@ -66,129 +66,3 @@ export function getSchemaName(
 
   return prettyName(schema, circular) ?? "";
 }
-
-export function getQualifierMessage(schema?: SchemaObject): string | undefined {
-  // TODO:
-  // - uniqueItems
-  // - maxProperties
-  // - minProperties
-  // - multipleOf
-  if (!schema) {
-    return undefined;
-  }
-
-  if (
-    schema.items &&
-    schema.minItems === undefined &&
-    schema.maxItems === undefined
-  ) {
-    return getQualifierMessage(schema.items);
-  }
-
-  let message = "**Possible values:** ";
-
-  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 = "";
-    let minLength;
-    let maxLength;
-    if (schema.minLength && schema.minLength > 1) {
-      minLength = `\`>= ${schema.minLength} characters\``;
-    }
-    if (schema.minLength && schema.minLength === 1) {
-      minLength = `\`non-empty\``;
-    }
-    if (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);
-  }
-
-  if (
-    schema.minimum != null ||
-    schema.maximum != null ||
-    typeof schema.exclusiveMinimum === "number" ||
-    typeof schema.exclusiveMaximum === "number"
-  ) {
-    let minmaxQualifier = "";
-    let minimum;
-    let maximum;
-    if (typeof schema.exclusiveMinimum === "number") {
-      minimum = `\`> ${schema.exclusiveMinimum}\``;
-    } else if (schema.minimum != null && !schema.exclusiveMinimum) {
-      minimum = `\`>= ${schema.minimum}\``;
-    } else if (schema.minimum != null && schema.exclusiveMinimum === true) {
-      minimum = `\`> ${schema.minimum}\``;
-    }
-    if (typeof schema.exclusiveMaximum === "number") {
-      maximum = `\`< ${schema.exclusiveMaximum}\``;
-    } else if (schema.maximum != null && !schema.exclusiveMaximum) {
-      maximum = `\`<= ${schema.maximum}\``;
-    } else if (schema.maximum != null && schema.exclusiveMaximum === true) {
-      maximum = `\`< ${schema.maximum}\``;
-    }
-
-    if (minimum && !maximum) {
-      minmaxQualifier += minimum;
-    }
-    if (maximum && !minimum) {
-      minmaxQualifier += maximum;
-    }
-    if (minimum && maximum) {
-      minmaxQualifier += `${minimum} and ${maximum}`;
-    }
-
-    qualifierGroups.push(minmaxQualifier);
-  }
-
-  if (schema.pattern) {
-    qualifierGroups.push(
-      `Value must match regular expression \`${schema.pattern}\``
-    );
-  }
-
-  // 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(`\`>= ${schema.minItems}\``);
-  }
-
-  if (schema.maxItems) {
-    qualifierGroups.push(`\`<= ${schema.maxItems}\``);
-  }
-
-  if (qualifierGroups.length === 0) {
-    return undefined;
-  }
-
-  return message + qualifierGroups.join(", ");
-}

package/src/markdown/utils.ts

@@ -129,7 +129,9 @@ export function create(
   } else {
     // Inline props as usual
     for (const [key, value] of Object.entries(rest)) {
-      propString += `\n  ${key}={${JSON.stringify(value)}}`;
+      if (value !== undefined) {
+        propString += `\n  ${key}={${JSON.stringify(value)}}`;
+      }
     }
   }
 

package/src/openapi/createSchemaExample.test.ts

@@ -54,4 +54,36 @@ describe("sampleFromSchema", () => {
       expect(result).toBe("dog");
     });
   });
+
+  describe("allOf with incompatible types", () => {
+    it("should return undefined when allOf contains incompatible types", () => {
+      const schema: SchemaObject = {
+        allOf: [{ type: "string" }, { type: "integer" }],
+      };
+      const context = { type: "request" as const };
+
+      const result = sampleFromSchema(schema, context);
+
+      expect(result).toBeUndefined();
+    });
+
+    it("should handle incompatible allOf types in a property", () => {
+      const schema: SchemaObject = {
+        type: "object",
+        properties: {
+          numero: {
+            allOf: [{ type: "string" }, { type: "integer" }],
+          },
+          name: {
+            type: "string",
+          },
+        },
+      };
+      const context = { type: "request" as const };
+
+      const result = sampleFromSchema(schema, context);
+
+      expect(result.name).toBe("string");
+    });
+  });
 });

package/src/openapi/openapi.test.ts

@@ -95,4 +95,180 @@ describe("openapi", () => {
       expect(schemaItems[0].id).toBe("without-tags");
     });
   });
+
+  describe("path template and custom verb handling", () => {
+    it("binds postman requests for OpenAPI templates and path verbs", async () => {
+      const openapiData = {
+        openapi: "3.0.0",
+        info: {
+          title: "Path Template API",
+          version: "1.0.0",
+        },
+        paths: {
+          "/api/resource:customVerb": {
+            post: {
+              summary: "Custom verb endpoint",
+              operationId: "customVerbOperation",
+              responses: {
+                "200": {
+                  description: "OK",
+                },
+              },
+            },
+          },
+          "/api/users/{id}": {
+            get: {
+              summary: "Get user by ID",
+              operationId: "getUserById",
+              parameters: [
+                {
+                  name: "id",
+                  in: "path",
+                  required: true,
+                  schema: {
+                    type: "string",
+                  },
+                },
+              ],
+              responses: {
+                "200": {
+                  description: "OK",
+                },
+              },
+            },
+          },
+          "/api/users/{userId}/posts/{postId}": {
+            get: {
+              summary: "Get user post",
+              operationId: "getUserPost",
+              parameters: [
+                {
+                  name: "userId",
+                  in: "path",
+                  required: true,
+                  schema: {
+                    type: "string",
+                  },
+                },
+                {
+                  name: "postId",
+                  in: "path",
+                  required: true,
+                  schema: {
+                    type: "string",
+                  },
+                },
+              ],
+              responses: {
+                "200": {
+                  description: "OK",
+                },
+              },
+            },
+          },
+          "/files/{name}.{ext}": {
+            get: {
+              summary: "Get file by name and extension",
+              operationId: "getFileByNameAndExt",
+              parameters: [
+                {
+                  name: "name",
+                  in: "path",
+                  required: true,
+                  schema: {
+                    type: "string",
+                  },
+                },
+                {
+                  name: "ext",
+                  in: "path",
+                  required: true,
+                  schema: {
+                    type: "string",
+                  },
+                },
+              ],
+              responses: {
+                "200": {
+                  description: "OK",
+                },
+              },
+            },
+          },
+          "/jobs/{id}:cancel": {
+            post: {
+              summary: "Cancel job",
+              operationId: "cancelJob",
+              parameters: [
+                {
+                  name: "id",
+                  in: "path",
+                  required: true,
+                  schema: {
+                    type: "string",
+                  },
+                },
+              ],
+              responses: {
+                "200": {
+                  description: "OK",
+                },
+              },
+            },
+          },
+        },
+      };
+
+      const options: APIOptions = {
+        specPath: "dummy",
+        outputDir: "build",
+      };
+      const sidebarOptions = {} as SidebarOptions;
+      const [items] = await processOpenapiFile(
+        openapiData as any,
+        options,
+        sidebarOptions
+      );
+
+      const apiItems = items.filter((item) => item.type === "api");
+      expect(apiItems).toHaveLength(5);
+
+      const customVerbItem = apiItems.find(
+        (item) => item.type === "api" && item.id === "custom-verb-operation"
+      ) as any;
+      expect(customVerbItem.api.path).toBe("/api/resource:customVerb");
+      expect(customVerbItem.api.method).toBe("post");
+      expect(customVerbItem.api.postman).toBeDefined();
+
+      const standardItem = apiItems.find(
+        (item) => item.type === "api" && item.id === "get-user-by-id"
+      ) as any;
+      expect(standardItem.api.path).toBe("/api/users/{id}");
+      expect(standardItem.api.method).toBe("get");
+      expect(standardItem.api.postman).toBeDefined();
+
+      const multiParamItem = apiItems.find(
+        (item) => item.type === "api" && item.id === "get-user-post"
+      ) as any;
+      expect(multiParamItem.api.path).toBe(
+        "/api/users/{userId}/posts/{postId}"
+      );
+      expect(multiParamItem.api.method).toBe("get");
+      expect(multiParamItem.api.postman).toBeDefined();
+
+      const sameSegmentItem = apiItems.find(
+        (item) => item.type === "api" && item.id === "get-file-by-name-and-ext"
+      ) as any;
+      expect(sameSegmentItem.api.path).toBe("/files/{name}.{ext}");
+      expect(sameSegmentItem.api.method).toBe("get");
+      expect(sameSegmentItem.api.postman).toBeDefined();
+
+      const templatedVerbItem = apiItems.find(
+        (item) => item.type === "api" && item.id === "cancel-job"
+      ) as any;
+      expect(templatedVerbItem.api.path).toBe("/jobs/{id}:cancel");
+      expect(templatedVerbItem.api.method).toBe("post");
+      expect(templatedVerbItem.api.postman).toBeDefined();
+    });
+  });
 });

package/src/openapi/openapi.ts

@@ -561,28 +561,44 @@ function createItems(
 /**
  * Attach Postman Request objects to the corresponding ApiItems.
  */
+function pathTemplateToRegex(pathTemplate: string): RegExp {
+  const pathWithTemplateTokens = pathTemplate.replace(
+    /\{[^}]+\}/g,
+    "__OPENAPI_PATH_PARAM__"
+  );
+  const escapedPathTemplate = pathWithTemplateTokens.replace(
+    /[.*+?^${}()|[\]\\]/g,
+    "\\$&"
+  );
+  const templatePattern = escapedPathTemplate.replace(
+    /__OPENAPI_PATH_PARAM__/g,
+    "[^/]+"
+  );
+  return new RegExp(`^${templatePattern}$`);
+}
+
 function bindCollectionToApiItems(
   items: ApiMetadata[],
   postmanCollection: sdk.Collection
 ) {
+  const apiMatchers = items
+    .filter((item): item is ApiPageMetadata => item.type === "api")
+    .map((item) => ({
+      apiItem: item,
+      method: item.api.method.toLowerCase(),
+      pathMatcher: pathTemplateToRegex(item.api.path),
+    }));
+
   postmanCollection.forEachItem((item: any) => {
     const method = item.request.method.toLowerCase();
-    const path = item.request.url
-      .getPath({ unresolved: true }) // unresolved returns "/:variableName" instead of "/<type>"
-      .replace(/(?<![a-z0-9-_]+):([a-z0-9-_]+)/gi, "{$1}"); // replace "/:variableName" with "/{variableName}"
-    const apiItem = items.find((item) => {
-      if (
-        item.type === "info" ||
-        item.type === "tag" ||
-        item.type === "schema"
-      ) {
-        return false;
-      }
-      return item.api.path === path && item.api.method === method;
-    });
+    const postmanPath = item.request.url.getPath({ unresolved: true });
+    const match = apiMatchers.find(
+      ({ method: itemMethod, pathMatcher }) =>
+        itemMethod === method && pathMatcher.test(postmanPath)
+    );
 
-    if (apiItem?.type === "api") {
-      apiItem.api.postman = item.request;
+    if (match) {
+      match.apiItem.api.postman = item.request;
     }
   });
 }

package/src/openapi/types.ts

@@ -65,6 +65,7 @@ export interface ContactObject {
 export interface LicenseObject {
   name: string;
   url?: string;
+  identifier?: string;
 }
 
 export interface ServerObject {

package/src/openapi/utils/loadAndResolveSpec.ts

@@ -6,9 +6,8 @@
  * ========================================================================== */
 
 import $RefParser from "@apidevtools/json-schema-ref-parser";
-import { bundle, Config } from "@redocly/openapi-core";
+import { bundle, createConfig } from "@redocly/openapi-core";
 import type { Source, Document } from "@redocly/openapi-core";
-import { ResolvedConfig } from "@redocly/openapi-core/lib/config";
 import chalk from "chalk";
 // @ts-ignore
 import { convertObj } from "swagger2openapi";
@@ -116,7 +115,7 @@ async function resolveJsonRefs(specUrlOrObject: object | string) {
 }
 
 export async function loadAndResolveSpec(specUrlOrObject: object | string) {
-  const config = new Config({} as ResolvedConfig);
+  const config = await createConfig({});
   const bundleOpts = {
     config,
     base: process.cwd(),
@@ -137,10 +136,13 @@ export async function loadAndResolveSpec(specUrlOrObject: object | string) {
   const {
     bundle: { parsed },
   } = await bundle(bundleOpts);
+  const parsedSpec = parsed as any;
 
   //Pre-processing before resolving JSON refs
-  if (parsed.components) {
-    for (let [component, type] of Object.entries(parsed.components) as any) {
+  if (parsedSpec.components) {
+    for (let [component, type] of Object.entries(
+      parsedSpec.components
+    ) as any) {
       if (component === "schemas") {
         for (let [schemaKey, schemaValue] of Object.entries(type) as any) {
           const title: string | undefined = schemaValue["title"];
@@ -152,7 +154,7 @@ export async function loadAndResolveSpec(specUrlOrObject: object | string) {
     }
   }
 
-  const resolved = await resolveJsonRefs(parsed);
+  const resolved = await resolveJsonRefs(parsedSpec);
 
   // Force serialization and replace circular $ref pointers
   // @ts-ignore