@kubb/agent 4.33.1 → 4.33.3

package/.output/server/node_modules/oas/dist/{chunk-BOVZLW7Q.js → chunk-HGVFNEKW.js}

@@ -1,22 +1,127 @@
 import {
-  findSchemaDefinition,
   supportedMethods
-} from "./chunk-LV26LN7C.js";
+} from "./chunk-VA3NKXX7.js";
 import {
   cloneObject,
+  dereferenceRef,
+  getDereferencingOptions,
   getParametersAsJSONSchema,
   getSchemaVersionString,
   isObject,
   isPrimitive,
   matches_mimetype_default,
   toJSONSchema
-} from "./chunk-SH63AK3O.js";
+} from "./chunk-5EP6HY2E.js";
 import {
   getExtension
-} from "./chunk-TTCGKV5E.js";
+} from "./chunk-S27IGTVG.js";
 import {
   isRef
-} from "./chunk-L3V5TF63.js";
+} from "./chunk-7MARUOFZ.js";
+
+// src/operation/index.ts
+import { $RefParser } from "@apidevtools/json-schema-ref-parser";
+
+// src/lib/build-discriminator-one-of.ts
+function hasDiscriminatorWithoutPolymorphism(schema) {
+  if (!schema || typeof schema !== "object") return false;
+  if (!("discriminator" in schema)) return false;
+  if ("oneOf" in schema || "anyOf" in schema) return false;
+  return true;
+}
+function allOfReferencesSchema(schema, targetSchemaName) {
+  if (!schema || typeof schema !== "object") return false;
+  if (!("allOf" in schema) || !Array.isArray(schema.allOf)) return false;
+  return schema.allOf.some((item) => {
+    if (isRef(item)) {
+      const refParts = item.$ref.split("/");
+      const refSchemaName = refParts[refParts.length - 1];
+      return refSchemaName === targetSchemaName;
+    }
+    return false;
+  });
+}
+function findDiscriminatorChildren(api) {
+  const childrenMap = /* @__PURE__ */ new Map();
+  const invertedChildrenMap = /* @__PURE__ */ new Map();
+  if (!api?.components?.schemas || typeof api.components.schemas !== "object") {
+    return { children: childrenMap, inverted: invertedChildrenMap };
+  }
+  const schemas = api.components.schemas;
+  const schemaNames = Object.keys(schemas);
+  const discriminatorSchemas = schemaNames.filter((name) => {
+    return hasDiscriminatorWithoutPolymorphism(schemas[name]);
+  });
+  for (const baseName of discriminatorSchemas) {
+    const baseSchema = schemas[baseName];
+    const discriminator = baseSchema.discriminator;
+    let childSchemaNames;
+    if (discriminator.mapping && typeof discriminator.mapping === "object") {
+      const mappingRefs = Object.values(discriminator.mapping);
+      if (mappingRefs.length > 0) {
+        childSchemaNames = mappingRefs.map((ref) => {
+          const parts = ref.split("/");
+          return parts[parts.length - 1];
+        });
+      }
+    }
+    if (!childSchemaNames || childSchemaNames.length === 0) {
+      childSchemaNames = schemaNames.filter((name) => {
+        if (name === baseName) return false;
+        return allOfReferencesSchema(schemas[name], baseName);
+      });
+    }
+    if (childSchemaNames.length > 0) {
+      childrenMap.set(baseName, childSchemaNames);
+    }
+  }
+  for (const [key, values] of childrenMap) {
+    for (const value of values) {
+      if (invertedChildrenMap.has(value)) {
+        invertedChildrenMap.get(value)?.push(key);
+      } else {
+        invertedChildrenMap.set(value, [key]);
+      }
+    }
+  }
+  return { children: childrenMap, inverted: invertedChildrenMap };
+}
+function buildDiscriminatorOneOf(api, childrenMap) {
+  if (!api?.components?.schemas || typeof api.components.schemas !== "object") {
+    return;
+  } else if (childrenMap.size === 0) {
+    return;
+  }
+  for (const [schemaName, childNames] of childrenMap) {
+    const schema = api.components.schemas[schemaName];
+    if (!schema) continue;
+    const oneOf = [];
+    for (const childName of childNames) {
+      if (api.components.schemas[childName]) {
+        oneOf.push(cloneObject(api.components.schemas[childName]));
+      }
+    }
+    if (oneOf.length > 0) {
+      schema.oneOf = oneOf;
+    }
+  }
+  for (const [parentSchemaName, childNames] of childrenMap) {
+    for (const childName of childNames) {
+      const childSchema = api.components.schemas[childName];
+      if (!childSchema || !("allOf" in childSchema) || !Array.isArray(childSchema.allOf)) {
+        continue;
+      }
+      for (let i = 0; i < childSchema.allOf.length; i++) {
+        const item = childSchema.allOf[i];
+        if (item && typeof item === "object" && "x-readme-ref-name" in item && item["x-readme-ref-name"] === parentSchemaName && "oneOf" in item) {
+          const clonedItem = cloneObject(item);
+          delete clonedItem.oneOf;
+          childSchema.allOf[i] = clonedItem;
+        }
+      }
+    }
+  }
+}
 
 // src/operation/lib/dedupe-common-parameters.ts
 function dedupeCommonParameters(parameters, commonParameters) {
@@ -251,7 +356,7 @@ function getMediaTypeExamples(mediaType, mediaTypeObject, opts = {}) {
         ret.description = description;
       }
       return ret;
-    }).filter(Boolean);
+    }).filter((item) => item !== false);
     if (multipleExamples.length) {
       return multipleExamples;
     }
@@ -271,15 +376,16 @@ function getMediaTypeExamples(mediaType, mediaTypeObject, opts = {}) {
 // src/operation/lib/get-response-examples.ts
 function getResponseExamples(operation) {
   return Object.keys(operation.responses || {}).map((status) => {
-    const response = operation.responses[status];
+    const response = operation.responses?.[status];
     let onlyHeaders = false;
-    if (isRef(response)) {
+    if (!response || isRef(response)) {
       return false;
     }
     const mediaTypes = {};
-    (response.content ? Object.keys(response.content) : []).forEach((mediaType) => {
+    (response?.content ? Object.keys(response.content) : []).forEach((mediaType) => {
       if (!mediaType) return;
-      const mediaTypeObject = response.content[mediaType];
+      const mediaTypeObject = response.content?.[mediaType];
+      if (!mediaTypeObject) return;
       const examples = getMediaTypeExamples(mediaType, mediaTypeObject, {
         includeReadOnly: true,
         includeWriteOnly: false
@@ -300,32 +406,35 @@ function getResponseExamples(operation) {
       mediaTypes,
       ...onlyHeaders ? { onlyHeaders } : {}
     };
-  }).filter(Boolean);
+  }).filter((item) => item !== false);
 }
 
 // src/operation/lib/get-callback-examples.ts
 function getCallbackExamples(operation) {
-  const ret = [];
-  return ret.concat(
-    ...Object.keys(operation.callbacks || {}).map((identifier) => {
-      const callback = operation.callbacks[identifier];
-      return [].concat(
-        ...Object.keys(callback).map((expression) => {
-          return Object.keys(callback[expression]).map((method) => {
-            const pathItem = callback[expression];
-            const example = getResponseExamples(pathItem[method]);
-            if (example.length === 0) return false;
-            return {
-              identifier,
-              expression,
-              method,
-              example
-            };
-          });
-        })
-      ).filter(Boolean);
-    })
-  );
+  if (!operation.callbacks) {
+    return [];
+  }
+  const examples = Object.keys(operation.callbacks).map((identifier) => {
+    const callback = operation.callbacks?.[identifier];
+    if (!callback || isRef(callback)) {
+      return [];
+    }
+    const items = Object.keys(callback).map((expression) => {
+      return Object.keys(callback[expression]).map((method) => {
+        const pathItem = callback[expression];
+        const example = getResponseExamples(pathItem[method]);
+        if (example.length === 0) return false;
+        return {
+          identifier,
+          expression,
+          method,
+          example
+        };
+      });
+    });
+    return items.flat().filter((item) => item !== false);
+  });
+  return examples.flat();
 }
 
 // src/operation/lib/get-example-groups.ts
@@ -341,7 +450,7 @@ function addMatchingResponseExamples(groups, operation) {
             status: example.status
           };
           if (!groups[mediaTypeExample.title].name) {
-            groups[mediaTypeExample.title].name = mediaTypeExample.summary;
+            groups[mediaTypeExample.title].name = mediaTypeExample.summary || mediaTypeExample.title;
           }
         }
       });
@@ -362,13 +471,15 @@ function getExampleGroups(operation) {
       namelessCodeSampleCounts[sample.language] = 1;
     }
     const name = getDefaultName(sample, namelessCodeSampleCounts);
-    if (groups[sample.correspondingExample]?.customCodeSamples?.length) {
-      groups[sample.correspondingExample].customCodeSamples.push({ ...sample, name, originalIndex: i });
-    } else if (sample.correspondingExample) {
-      groups[sample.correspondingExample] = {
-        name,
-        customCodeSamples: [{ ...sample, name, originalIndex: i }]
-      };
+    if (sample.correspondingExample) {
+      if (groups[sample.correspondingExample]?.customCodeSamples?.length) {
+        groups[sample.correspondingExample].customCodeSamples.push({ ...sample, name, originalIndex: i });
+      } else if (sample.correspondingExample) {
+        groups[sample.correspondingExample] = {
+          name,
+          customCodeSamples: [{ ...sample, name, originalIndex: i }]
+        };
+      }
     } else if (groups[noCorrespondingResponseKey]?.customCodeSamples?.length) {
       groups[noCorrespondingResponseKey].customCodeSamples.push({ ...sample, name, originalIndex: i });
     } else {
@@ -384,9 +495,12 @@ function getExampleGroups(operation) {
   }
   operation.getParameters().forEach((param) => {
     Object.entries(param.examples || {}).forEach(([exampleKey, paramExample]) => {
+      if (isRef(paramExample)) {
+        return;
+      }
       groups[exampleKey] = {
         ...groups[exampleKey],
-        name: groups[exampleKey]?.name || paramExample.summary,
+        name: groups[exampleKey]?.name || paramExample.summary || exampleKey,
         request: {
           ...groups[exampleKey]?.request,
           [param.in]: {
@@ -403,7 +517,7 @@ function getExampleGroups(operation) {
         const mediaType = requestExample.mediaType === "application/x-www-form-urlencoded" ? "formData" : "body";
         groups[mediaTypeExample.title] = {
           ...groups[mediaTypeExample.title],
-          name: groups[mediaTypeExample.title]?.name || mediaTypeExample.summary,
+          name: groups[mediaTypeExample.title]?.name || mediaTypeExample.summary || mediaTypeExample.title,
           request: {
             ...groups[mediaTypeExample.title]?.request,
             [mediaType]: mediaTypeExample.value
@@ -426,7 +540,7 @@ function getExampleGroups(operation) {
 // src/operation/lib/get-requestbody-examples.ts
 function getRequestBodyExamples(operation) {
   const requestBody = operation.requestBody;
-  if (!requestBody || !requestBody.content) {
+  if (!requestBody || isRef(requestBody) || !requestBody.content) {
     return [];
   }
   return Object.keys(requestBody.content || {}).map((mediaType) => {
@@ -442,29 +556,36 @@ function getRequestBodyExamples(operation) {
       mediaType,
       examples
     };
-  }).filter((x) => x !== false);
+  }).filter((item) => item !== false);
 }
 
 // src/operation/lib/get-response-as-json-schema.ts
 var isJSON = matches_mimetype_default.json;
 function buildHeadersSchema(response, opts) {
-  const headers = response.headers;
   const headersSchema = {
     type: "object",
     properties: {}
   };
-  Object.keys(headers).forEach((key) => {
-    if (headers[key] && headers[key].schema) {
-      const header = headers[key];
-      headersSchema.properties[key] = toJSONSchema(header.schema, {
-        addEnumsToDescriptions: true,
-        transformer: opts.transformer
-      });
-      if (header.description) {
-        headersSchema.properties[key].description = header.description;
+  if (response.headers) {
+    Object.keys(response.headers).forEach((key) => {
+      if (!response.headers?.[key] || isRef(response.headers?.[key])) {
+        return;
       }
-    }
-  });
+      if (response.headers[key].schema) {
+        const header = response.headers[key];
+        if (!header.schema || isRef(header.schema)) {
+          return;
+        }
+        headersSchema.properties[key] = toJSONSchema(header.schema, {
+          addEnumsToDescriptions: true,
+          transformer: opts?.transformer
+        });
+        if (header.description) {
+          headersSchema.properties[key].description = header.description;
+        }
+      }
+    });
+  }
   const headersWrapper = {
     schema: headersSchema,
     type: "object",
@@ -500,28 +621,43 @@ function getResponseAsJSONSchema(operation, api, statusCode, opts) {
     }
     if (preferredContentType) {
       if (contentTypes.includes(preferredContentType)) {
-        return toJSONSchema(cloneObject(content[preferredContentType].schema), {
+        const schema2 = cloneObject(content[preferredContentType].schema);
+        if (!schema2) {
+          return null;
+        }
+        return toJSONSchema(schema2, {
           addEnumsToDescriptions: true,
           refLogger,
-          transformer: opts.transformer
+          transformer: opts?.transformer
         });
       }
       return null;
     }
     for (let i = 0; i < contentTypes.length; i++) {
       if (isJSON(contentTypes[i])) {
-        return toJSONSchema(cloneObject(content[contentTypes[i]].schema), {
+        const schema2 = cloneObject(content[contentTypes[i]].schema);
+        if (!schema2) {
+          return {};
+        }
+        return toJSONSchema(schema2, {
           addEnumsToDescriptions: true,
           refLogger,
-          transformer: opts.transformer
+          transformer: opts?.transformer
         });
       }
     }
     const contentType = contentTypes.shift();
-    return toJSONSchema(cloneObject(content[contentType].schema), {
+    if (!contentType) {
+      return {};
+    }
+    const schema = cloneObject(content[contentType].schema);
+    if (!schema) {
+      return {};
+    }
+    return toJSONSchema(schema, {
       addEnumsToDescriptions: true,
       refLogger,
-      transformer: opts.transformer
+      transformer: opts?.transformer
     });
   }
   const foundSchema = getPreferredSchema(response.content, opts?.contentType);
@@ -545,8 +681,10 @@ function getResponseAsJSONSchema(operation, api, statusCode, opts) {
       schemaWrapper.description = response.description;
     }
     if (api.components && schemaWrapper.schema) {
-      if (hasCircularRefs || hasDiscriminatorMappingRefs && opts.includeDiscriminatorMappingRefs) {
-        schemaWrapper.schema.components = api.components;
+      if (hasCircularRefs || hasDiscriminatorMappingRefs && opts?.includeDiscriminatorMappingRefs) {
+        schemaWrapper.schema.components = cloneObject(
+          api.components
+        );
       }
     }
     jsonSchema.push(schemaWrapper);
@@ -559,7 +697,7 @@ function getResponseAsJSONSchema(operation, api, statusCode, opts) {
 
 // src/operation/lib/operationId.ts
 function hasOperationId(operation) {
-  return Boolean("operationId" in operation && operation.operationId.length);
+  return Boolean("operationId" in operation && operation.operationId?.length);
 }
 function getOperationId(path, method, operation, opts = {}) {
   function sanitize(id) {
@@ -642,6 +780,17 @@ var Operation = class {
    * Flattened out arrays of both request and response headers that are utilized on this operation.
    */
   headers;
+  /**
+   * Internal storage array that the library utilizes to keep track of the times the
+   * {@see Operation.dereference} has been called so that if you initiate multiple promises they'll
+   * all end up returning the same data set once the initial dereference call completed.
+   */
+  promises;
+  /**
+   * Internal storage array that the library utilizes to keep track of its `dereferencing` state so
+   * it doesn't initiate multiple dereferencing processes.
+   */
+  dereferencing;
   constructor(api, path, method, operation) {
     this.schema = operation;
     this.api = api;
@@ -656,33 +805,62 @@ var Operation = class {
       request: [],
       response: []
     };
+    this.promises = [];
+    this.dereferencing = {
+      processing: false,
+      complete: false,
+      circularRefs: []
+    };
   }
+  /**
+   * Retrieve the `summary` for this operation.
+   *
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationsummary}
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-summary}
+   */
   getSummary() {
     if (this.schema?.summary && typeof this.schema.summary === "string") {
       return this.schema.summary;
-    } else if (this.api.paths[this.path].summary && typeof this.api.paths[this.path].summary === "string") {
-      return this.api.paths[this.path].summary;
+    }
+    const pathItem = this.api.paths?.[this.path];
+    if (pathItem?.summary && typeof pathItem.summary === "string") {
+      return pathItem.summary;
     }
     return void 0;
   }
+  /**
+   * Retrieve the `description` for this operation.
+   *
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationdescription}
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-description}
+   */
   getDescription() {
     if (this.schema?.description && typeof this.schema.description === "string") {
       return this.schema.description;
-    } else if (this.api.paths[this.path].description && typeof this.api.paths[this.path].description === "string") {
-      return this.api.paths[this.path].description;
+    }
+    const pathItem = this.api.paths?.[this.path];
+    if (pathItem?.description && typeof pathItem.description === "string") {
+      return pathItem.description;
     }
     return void 0;
   }
+  /**
+   * Retrieve the primary content type for this operation. If multiple exist, the first JSON-like
+   * type will be returned.
+   *
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-requestbodycontent}
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-request-body-content}
+   */
   getContentType() {
     if (this.contentType) {
       return this.contentType;
     }
     let types = [];
     if (this.schema.requestBody) {
-      if ("$ref" in this.schema.requestBody) {
-        this.schema.requestBody = findSchemaDefinition(this.schema.requestBody.$ref, this.api);
+      if (isRef(this.schema.requestBody)) {
+        this.schema.requestBody = dereferenceRef(this.schema.requestBody, this.api);
       }
-      if ("content" in this.schema.requestBody) {
+      if (this.schema.requestBody && "content" in this.schema.requestBody) {
         types = Object.keys(this.schema.requestBody.content);
       }
     }
@@ -697,21 +875,46 @@ var Operation = class {
     });
     return this.contentType;
   }
+  /**
+   * Checks if the current operation has a `x-www-form-urlencoded` content type payload.
+   *
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-requestbodycontent}
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-request-body-content}
+   */
   isFormUrlEncoded() {
     return matches_mimetype_default.formUrlEncoded(this.getContentType());
   }
+  /**
+   * Checks if the current operation has a mutipart content type payload.
+   *
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-requestbodycontent}
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-request-body-content}
+   */
   isMultipart() {
     return matches_mimetype_default.multipart(this.getContentType());
   }
+  /**
+   * Checks if the current operation has a JSON-like content type payload.
+   *
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-requestbodycontent}
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-request-body-content}
+   */
   isJson() {
     return matches_mimetype_default.json(this.getContentType());
   }
+  /**
+   * Checks if the current operation has an XML content type payload.
+   *
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-requestbodycontent}
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-request-body-content}
+   */
   isXml() {
     return matches_mimetype_default.xml(this.getContentType());
   }
   /**
    * Checks if the current operation is a webhook or not.
    *
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#oas-webhooks}
    */
   isWebhook() {
     return this instanceof Webhook;
@@ -721,6 +924,8 @@ var Operation = class {
    * defined at the operation level, the securities for the entire API definition are returned
    * (with an empty array as a final fallback).
    *
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#security-requirement-object}
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#security-requirement-object}
    */
   getSecurity() {
     if (!this.api?.components?.securitySchemes || !Object.keys(this.api.components.securitySchemes).length) {
@@ -739,8 +944,7 @@ var Operation = class {
    *    security schemes, rather than returning `false`.
    */
   getSecurityWithTypes(filterInvalid = false) {
-    const securityRequirements = this.getSecurity();
-    return securityRequirements.map((requirement) => {
+    return this.getSecurity().map((requirement) => {
       let keys;
       try {
         keys = Object.keys(requirement);
@@ -750,6 +954,9 @@ var Operation = class {
       const keysWithTypes = keys.map((key) => {
         let security;
         try {
+          if (!this.api.components?.securitySchemes?.[key] || isRef(this.api.components.securitySchemes[key])) {
+            return false;
+          }
           security = this.api.components.securitySchemes[key];
         } catch {
           return false;
@@ -789,8 +996,7 @@ var Operation = class {
    *
    */
   prepareSecurity() {
-    const securitiesWithTypes = this.getSecurityWithTypes();
-    return securitiesWithTypes.reduce(
+    return this.getSecurityWithTypes().reduce(
       (prev, securities) => {
         if (!securities) return prev;
         securities.forEach((security) => {
@@ -807,12 +1013,17 @@ var Operation = class {
       {}
     );
   }
+  /**
+   * Retrieve all of the headers, request and response, that are associated with this operation.
+   *
+   */
   getHeaders() {
     const security = this.prepareSecurity();
     if (security.Header) {
       this.headers.request = security.Header.map((h) => {
+        if (!("name" in h)) return false;
         return h.name;
-      });
+      }).filter((item) => item !== false);
     }
     if (security.Bearer || security.Basic || security.OAuth2) {
       this.headers.request.push("Authorization");
@@ -822,30 +1033,38 @@ var Operation = class {
     }
     if (this.schema.parameters) {
       this.headers.request = this.headers.request.concat(
-        // Remove the reference object because we will have already dereferenced.
         this.schema.parameters.map((p) => {
+          if (isRef(p)) {
+            return void 0;
+          }
           if (p.in && p.in === "header") return p.name;
           return void 0;
-        }).filter((p) => p)
+        }).filter((item) => item !== void 0)
       );
     }
     if (this.schema.responses) {
-      this.headers.response = Object.keys(this.schema.responses).filter((r) => this.schema.responses[r].headers).map(
-        (r) => (
-          // Remove the reference object because we will have already dereferenced.
-          Object.keys(this.schema.responses[r].headers)
-        )
-      ).reduce((a, b) => a.concat(b), []);
+      this.headers.response = Object.keys(this.schema.responses).map((r) => {
+        const response = this.schema.responses?.[r];
+        if (!response || isRef(response)) {
+          return [];
+        }
+        return response?.headers ? Object.keys(response.headers) : [];
+      }).reduce((a, b) => a.concat(b), []);
     }
     if (!this.headers.request.includes("Content-Type") && this.schema.requestBody) {
-      if (this.schema.requestBody.content && Object.keys(this.schema.requestBody.content)) {
+      const requestBody = this.schema.requestBody;
+      if (requestBody && !isRef(requestBody) && "content" in requestBody && Object.keys(requestBody.content)) {
         this.headers.request.push("Content-Type");
       }
     }
     if (this.schema.responses) {
-      if (Object.keys(this.schema.responses).some(
-        (response) => !!this.schema.responses[response].content
-      )) {
+      if (Object.keys(this.schema.responses).some((r) => {
+        const response = this.schema.responses?.[r];
+        if (!response || isRef(response)) {
+          return false;
+        }
+        return response?.content && Object.keys(response.content).length > 0;
+      })) {
         if (!this.headers.request.includes("Accept")) this.headers.request.push("Accept");
         if (!this.headers.response.includes("Content-Type")) this.headers.response.push("Content-Type");
       }
@@ -853,17 +1072,21 @@ var Operation = class {
     return this.headers;
   }
   /**
-   * Determine if the operation has an `operationId` present in its schema. Note that if one is
-   * present in the schema but is an empty string then this will return false.
+   * Determine if this operation has an `operationId` present in its schema. Note that if one is
+   * present in the schema but is an empty string then this will return `false`.
    *
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationid}
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-id}
    */
   hasOperationId() {
     return hasOperationId(this.schema);
   }
   /**
    * Determine if an operation has an `operationId` present in its schema. Note that if one is
-   * present in the schema but is an empty string then this will return false.
+   * present in the schema but is an empty string then this will return `false`.
    *
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationid}
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-id}
    */
   static hasOperationId(schema) {
     return hasOperationId(schema);
@@ -872,6 +1095,8 @@ var Operation = class {
    * Get an `operationId` for this operation. If one is not present (it's not required by the spec!)
    * a hash of the path and method will be returned instead.
    *
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationid}
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-id}
    */
   getOperationId(opts = {}) {
     return getOperationId(this.path, this.method, this.schema, opts);
@@ -880,6 +1105,8 @@ var Operation = class {
    * Get an `operationId` for an operation. If one is not present (it's not required by the spec!)
    * a hash of the path and method will be returned instead.
    *
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationid}
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-id}
    */
   static getOperationId(path, method, schema, opts = {}) {
     return getOperationId(path, method, schema, opts);
@@ -893,7 +1120,7 @@ var Operation = class {
       return [];
     }
     const oasTagMap = /* @__PURE__ */ new Map();
-    if ("tags" in this.api) {
+    if (Array.isArray(this.api?.tags)) {
       this.api.tags.forEach((tag) => {
         oasTagMap.set(tag.name, tag);
       });
@@ -916,9 +1143,11 @@ var Operation = class {
   /**
    * Return is the operation is flagged as `deprecated` or not.
    *
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationdeprecated}
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-deprecated}
    */
   isDeprecated() {
-    return "deprecated" in this.schema ? this.schema.deprecated : false;
+    return Boolean("deprecated" in this.schema ? this.schema.deprecated : false);
   }
   /**
    * Determine if the operation has any (non-request body) parameters.
@@ -930,10 +1159,17 @@ var Operation = class {
   /**
    * Return the parameters (non-request body) on the operation.
    *
+   * @todo Add support for `ReferenceObject`
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationparameters}
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-parameters}
    */
   getParameters() {
-    let parameters = this.schema?.parameters || [];
-    const commonParams = this.api?.paths?.[this.path]?.parameters || [];
+    let parameters = (this.schema?.parameters || []).filter(
+      (param) => param && !isRef(param)
+    );
+    const commonParams = (this.api?.paths?.[this.path]?.parameters || []).filter(
+      (param) => param && !isRef(param)
+    );
     if (commonParams.length) {
       parameters = parameters.concat(dedupeCommonParameters(parameters, commonParams) || []);
     }
@@ -942,6 +1178,8 @@ var Operation = class {
   /**
    * Determine if this operation has any required parameters.
    *
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationparameters}
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-parameters}
    */
   hasRequiredParameters() {
     return this.getParameters().some((param) => "required" in param && param.required);
@@ -983,6 +1221,8 @@ var Operation = class {
   /**
    * Determine if the operation has any request bodies.
    *
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#user-content-operationrequestbody}
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#user-content-operation-request-body}
    */
   hasRequestBody() {
     return !!this.schema.requestBody;
@@ -998,7 +1238,7 @@ var Operation = class {
       return [];
     }
     const requestBody = this.schema.requestBody;
-    if (isRef(requestBody)) {
+    if (!requestBody || isRef(requestBody)) {
       return [];
     }
     return Object.keys(requestBody.content);
@@ -1006,19 +1246,25 @@ var Operation = class {
   /**
    * Determine if this operation has a required request body.
    *
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#media-type-object}
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#media-type-object}
    */
   hasRequiredRequestBody() {
     if (!this.hasRequestBody()) {
       return false;
     }
     const requestBody = this.schema.requestBody;
-    if (isRef(requestBody)) {
+    if (!requestBody || isRef(requestBody)) {
       return false;
     }
     if (requestBody.required) {
       return true;
     }
-    return !!this.getParametersAsJSONSchema().filter((js) => ["body", "formData"].includes(js.type)).find((js) => js.schema && Array.isArray(js.schema.required) && js.schema.required.length);
+    const parameters = this.getParametersAsJSONSchema();
+    if (parameters === null) {
+      return false;
+    }
+    return !!parameters.filter((js) => ["body", "formData"].includes(js.type)).find((js) => js.schema && Array.isArray(js.schema.required) && js.schema.required.length);
   }
   /**
    * Retrieve a specific request body content schema off this operation.
@@ -1037,7 +1283,7 @@ var Operation = class {
       return false;
     }
     const requestBody = this.schema.requestBody;
-    if (isRef(requestBody)) {
+    if (!requestBody || isRef(requestBody)) {
       return false;
     }
     if (mediaType) {
@@ -1072,6 +1318,8 @@ var Operation = class {
   /**
    * Retrieve an array of request body examples that this operation has.
    *
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#request-body-examples}
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#request-body-examples}
    */
   getRequestBodyExamples() {
     const isRequestExampleValueDefined = typeof this.requestBodyExamples?.[0]?.examples?.[0].value !== "undefined";
@@ -1085,16 +1333,15 @@ var Operation = class {
    * Return a specific response out of the operation by a given HTTP status code.
    *
    * @param statusCode Status code to pull a response object for.
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#response-object}
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#response-object}
    */
   getResponseByStatusCode(statusCode) {
     if (!this.schema.responses) {
       return false;
     }
-    if (typeof this.schema.responses[statusCode] === "undefined") {
-      return false;
-    }
     const response = this.schema.responses[statusCode];
-    if (isRef(response)) {
+    if (!response || isRef(response)) {
       return false;
     }
     return response;
@@ -1102,6 +1349,8 @@ var Operation = class {
   /**
    * Retrieve an array of response examples that this operation has.
    *
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#response-object-examples}
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.2.md#response-object-examples}
    */
   getResponseExamples() {
     if (this.responseExamples) {
@@ -1113,9 +1362,11 @@ var Operation = class {
   /**
    * Determine if the operation has callbacks.
    *
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#callback-object}
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callback-object}
    */
   hasCallbacks() {
-    return !!this.schema.callbacks;
+    return Boolean(this.schema.callbacks);
   }
   /**
    * Retrieve a specific callback.
@@ -1128,36 +1379,51 @@ var Operation = class {
    */
   getCallback(identifier, expression, method) {
     if (!this.schema.callbacks) return false;
-    const callback = this.schema.callbacks[identifier] ? this.schema.callbacks[identifier][expression] : false;
-    if (!callback || !callback[method]) return false;
+    const callbackObj = this.schema.callbacks[identifier];
+    if (!callbackObj || isRef(callbackObj)) {
+      return false;
+    }
+    const callback = callbackObj[expression];
+    if (!callback || isRef(callback) || !callback[method]) {
+      return false;
+    }
     return new Callback(this.api, expression, method, callback[method], identifier, callback);
   }
   /**
    * Retrieve an array of operations created from each callback.
    *
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#callback-object}
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callback-object}
    */
   getCallbacks() {
-    const callbackOperations = [];
-    if (!this.hasCallbacks()) return false;
-    Object.keys(this.schema.callbacks).forEach((callback) => {
-      Object.keys(this.schema.callbacks[callback]).forEach((expression) => {
-        const cb = this.schema.callbacks[callback];
-        if (!isRef(cb)) {
-          const exp = cb[expression];
-          if (!isRef(exp)) {
-            Object.keys(exp).forEach((method) => {
-              if (!supportedMethods.includes(method)) return;
-              callbackOperations.push(this.getCallback(callback, expression, method));
-            });
-          }
+    if (!this.hasCallbacks()) return [];
+    const callbacks = [];
+    Object.keys(this.schema.callbacks || {}).forEach((callback) => {
+      const cb = this.schema.callbacks?.[callback];
+      if (!cb || isRef(cb)) {
+        return;
+      }
+      Object.keys(cb).forEach((expression) => {
+        const exp = cb[expression];
+        if (!exp || isRef(exp)) {
+          return;
         }
+        Object.keys(exp).forEach((method) => {
+          if (!supportedMethods.includes(method)) return;
+          const found = this.getCallback(callback, expression, method);
+          if (found) {
+            callbacks.push(found);
+          }
+        });
       });
     });
-    return callbackOperations;
+    return callbacks;
   }
   /**
    * Retrieve an array of callback examples that this operation has.
    *
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#callback-object}
+   * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callback-object}
    */
   getCallbackExamples() {
     if (this.callbackExamples) {
@@ -1205,6 +1471,121 @@ var Operation = class {
     this.exampleGroups = groups;
     return groups;
   }
+  /**
+   * Dereference the current operation schema so it can be parsed free of worries of `$ref` schemas
+   * and circular structures.
+   *
+   */
+  async dereference(opts) {
+    if (this.dereferencing.complete) {
+      return Promise.resolve(true);
+    }
+    if (this.dereferencing.processing) {
+      return new Promise((resolve, reject) => {
+        this.promises.push({ resolve, reject });
+      });
+    }
+    this.dereferencing.processing = true;
+    const { children: discriminatorChildrenMap, inverted: discriminatorChildrenMapInverted } = findDiscriminatorChildren(this.api);
+    const { api, schema, promises } = this;
+    if (api?.components?.schemas && typeof api.components.schemas === "object") {
+      Object.keys(api.components.schemas).forEach((schemaName) => {
+        if (isPrimitive(api.components?.schemas?.[schemaName]) || Array.isArray(api.components?.schemas?.[schemaName]) || api.components?.schemas?.[schemaName] === null) {
+          return;
+        }
+        (api.components?.schemas?.[schemaName])["x-readme-ref-name"] = schemaName;
+      });
+    }
+    const circularRefs = /* @__PURE__ */ new Set();
+    const dereferencingOptions = getDereferencingOptions(circularRefs);
+    const parser = new $RefParser();
+    return parser.dereference(
+      "#/__INTERNAL__",
+      {
+        // Because `json-schema-ref-parser` will dereference this entire object as we only want
+        // to dereference this operation schema we're attaching it to the `__INTERNAL__` key, and
+        // later using that to extract our dereferenced schema. If we didn't do this then we run
+        // the risk of any keyword in `schema` being overriden by `paths` and `components`.
+        //
+        // This solution isn't the best and still requires us to send `json-schema-ref-parser`
+        // basically the entire API defintiion but because we don't know what `$ref` pointers in
+        // `schema` reference, we can't know which parts of full API definition we could safely
+        // exclude from this process.
+        __INTERNAL__: structuredClone(schema),
+        paths: api.paths ?? void 0,
+        components: api.components ?? void 0
+      },
+      {
+        ...dereferencingOptions,
+        dereference: {
+          ...dereferencingOptions.dereference,
+          /**
+           * Because we only want to dereference our `__INTERNAL__` schema, not the **entire**
+           * API definition if the parser attemps to dereference anything but that then we
+           * should bail out of that crawler.
+           *
+           * @fixme this may cause issues where a path references a schema within itself to be ignored.
+           */
+          excludedPathMatcher: (path) => {
+            if (path === "#/paths" || path.startsWith("#/paths/")) {
+              return true;
+            }
+            if (discriminatorChildrenMap.size > 0 || discriminatorChildrenMapInverted.size > 0) {
+              if (path.startsWith("#/components/") && path !== "#/components/schemas" && !path.startsWith("#/components/schemas/")) {
+                return true;
+              }
+              if (path.startsWith("#/components/schemas/")) {
+                const schemaName = path.split("/").pop();
+                if (schemaName && (discriminatorChildrenMap.has(schemaName) || discriminatorChildrenMapInverted.has(schemaName))) {
+                  if (path === `#/components/schemas/${schemaName}` || path.startsWith(`#/components/schemas/${schemaName}/`)) {
+                    return false;
+                  }
+                  return true;
+                }
+              }
+              return false;
+            }
+            return path === "#/components" || path.startsWith("#/components/");
+          }
+        }
+      }
+    ).then((res) => {
+      const dereferenced = res;
+      if (dereferenced?.components?.schemas && discriminatorChildrenMap.size > 0) {
+        buildDiscriminatorOneOf({ components: dereferenced.components }, discriminatorChildrenMap);
+      }
+      this.schema = dereferenced.__INTERNAL__;
+      this.promises = promises;
+      this.dereferencing = {
+        processing: false,
+        complete: true,
+        // We need to convert our `Set` to an array in order to match the typings.
+        circularRefs: [...circularRefs]
+      };
+      if (opts?.cb) {
+        opts.cb();
+      }
+    }).then(() => {
+      return this.promises.map((deferred) => deferred.resolve());
+    }).catch((err) => {
+      this.dereferencing.processing = false;
+      this.promises.map((deferred) => deferred.reject(err));
+      throw err;
+    });
+  }
+  /**
+   * Retrieve any circular `$ref` pointers that maybe present within operation schema.
+   *
+   * This method requires that you first dereference the definition.
+   *
+   * @see Operation.dereference
+   */
+  getCircularReferences() {
+    if (!this.dereferencing.complete) {
+      throw new Error(".dereference() must be called first in order for this method to obtain circular references.");
+    }
+    return this.dereferencing.circularRefs;
+  }
 };
 var Callback = class extends Operation {
   /**
@@ -1258,22 +1639,32 @@ var Webhook = class extends Operation {
   getSummary() {
     if (this.schema?.summary && typeof this.schema.summary === "string") {
       return this.schema.summary;
-    } else if (this.api.webhooks[this.path].summary && typeof this.api.webhooks[this.path].summary === "string") {
-      return this.api.webhooks[this.path].summary;
+    }
+    const webhookPath = this.api.webhooks?.[this.path];
+    if (webhookPath && !isRef(webhookPath)) {
+      if (webhookPath?.summary && typeof webhookPath.summary === "string") {
+        return webhookPath.summary;
+      }
     }
     return void 0;
   }
   getDescription() {
     if (this.schema?.description && typeof this.schema.description === "string") {
       return this.schema.description;
-    } else if (this.api.webhooks[this.path].description && typeof this.api.webhooks[this.path].description === "string") {
-      return this.api.webhooks[this.path].description;
+    }
+    const webhookPath = this.api.webhooks?.[this.path];
+    if (webhookPath && !isRef(webhookPath)) {
+      if (webhookPath?.description && typeof webhookPath.description === "string") {
+        return webhookPath.description;
+      }
     }
     return void 0;
   }
 };
 
 export {
+  findDiscriminatorChildren,
+  buildDiscriminatorOneOf,
   Operation,
   Callback,
   Webhook
@@ -1290,4 +1681,4 @@ export {
  * @license Apache-2.0
  * @see {@link https://github.com/swagger-api/swagger-ui/blob/master/src/core/plugins/samples/fn.js}
  */
-//# sourceMappingURL=chunk-BOVZLW7Q.js.map
+//# sourceMappingURL=chunk-HGVFNEKW.js.map