refactor: Reuse parseExtensions and remove JSDoc from extension fields

- Made parseExtensions generic and exportable from schema parsers
- Reused parseExtensions in parameter and operation parsers
- Removed JSDoc comments from extension field index signatures

Co-authored-by: mrlubos <[e-mail]>

packages/openapi-ts/src/ir/types.d.ts

···
 }
 
 export interface IROperationObject {
-  /**
-   * OpenAPI extension fields (x-*) from the original operation.
-   * These are custom fields that can be used by plugins.
-   */
   [extension: `x-${string}`]: unknown;
   body?: IRBodyObject;
   deprecated?: boolean;
···
 
 interface IRParameterObject
   extends Pick<JsonSchemaDraft2020_12, 'deprecated' | 'description'> {
-  /**
-   * OpenAPI extension fields (x-*) from the original parameter.
-   * These are custom fields that can be used by plugins.
-   */
   [extension: `x-${string}`]: unknown;
   /**
    * Determines whether the parameter value SHOULD allow reserved characters, as defined by RFC3986 `:/?#[]@!$&'()*+,;=` to be included without percent-encoding. The default value is `false`. This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded` or `multipart/form-data`. If a value is explicitly defined, then the value of `contentType` (implicit or explicit) SHALL be ignored.
···
     | 'title'
     | 'example'
   > {
-  /**
-   * OpenAPI extension fields (x-*) from the original schema.
-   * These are custom fields that can be used by plugins.
-   */
   [extension: `x-${string}`]: unknown;
   /**
    * If the schema is intended to be used as an object property, it can be

packages/openapi-ts/src/openApi/2.0.x/parser/operation.ts

···
 } from '../types/spec';
 import { contentToSchema, mediaTypeObjects } from './mediaType';
 import { paginationField } from './pagination';
-import { schemaToIrSchema } from './schema';
+import { parseExtensions, schemaToIrSchema } from './schema';
 
 interface Operation
   extends Omit<OperationObject, 'parameters'>,
···
     operation,
   });
 
-  // Copy extension fields
-  for (const key in operation) {
-    if (key.startsWith('x-')) {
-      (irOperation as unknown as Record<string, unknown>)[key] =
-        operation[key as keyof Operation];
-    }
-  }
+  parseExtensions({
+    source: operation,
+    target: irOperation,
+  });
 
   return irOperation;
 };

packages/openapi-ts/src/openApi/2.0.x/parser/parameter.ts

···
   SchemaObject,
 } from '../types/spec';
 import { paginationField } from './pagination';
-import { schemaToIrSchema } from './schema';
+import { parseExtensions, schemaToIrSchema } from './schema';
 
 type Parameter = Exclude<ParameterObject, { in: 'body' }>;
 
···
     irParameter.required = parameter.required;
   }
 
-  // Copy extension fields
-  for (const key in parameter) {
-    if (key.startsWith('x-')) {
-      (irParameter as unknown as Record<string, unknown>)[key] =
-        parameter[key as keyof ParameterObject];
-    }
-  }
+  parseExtensions({
+    source: parameter,
+    target: irParameter,
+  });
 
   return irParameter;
 };

packages/openapi-ts/src/openApi/2.0.x/parser/schema.ts

···
   return irSchema;
 };
 
-const parseExtensions = ({
-  irSchema,
-  schema,
+export const parseExtensions = <T extends Record<string, unknown>>({
+  source,
+  target,
 }: {
-  irSchema: IR.SchemaObject;
-  schema: SchemaObject;
+  source: T;
+  target: Record<string, unknown>;
 }) => {
-  // Copy all x-* extension fields from the source schema to the IR schema
-  for (const key in schema) {
+  for (const key in source) {
     if (key.startsWith('x-')) {
-      (irSchema as unknown as Record<string, unknown>)[key] =
-        schema[key as keyof SchemaObject];
+      target[key] = source[key];
     }
   }
 };
···
   });
 
   parseExtensions({
-    irSchema,
-    schema,
+    source: schema,
+    target: irSchema,
   });
 
   return irSchema;

packages/openapi-ts/src/openApi/3.0.x/parser/operation.ts

···
 } from '../types/spec';
 import { contentToSchema, mediaTypeObjects } from './mediaType';
 import { paginationField } from './pagination';
-import { schemaToIrSchema } from './schema';
+import { parseExtensions, schemaToIrSchema } from './schema';
 
 interface Operation
   extends Omit<OperationObject, 'parameters'>,
···
     operation,
   });
 
-  // Copy extension fields
-  for (const key in operation) {
-    if (key.startsWith('x-')) {
-      (irOperation as unknown as Record<string, unknown>)[key] =
-        operation[key as keyof Operation];
-    }
-  }
+  parseExtensions({
+    source: operation,
+    target: irOperation,
+  });
 
   return irOperation;
 };

packages/openapi-ts/src/openApi/3.0.x/parser/parameter.ts

···
 } from '../types/spec';
 import { mediaTypeObjects } from './mediaType';
 import { paginationField } from './pagination';
-import { schemaToIrSchema } from './schema';
+import { parseExtensions, schemaToIrSchema } from './schema';
 
 /**
  * Returns default parameter `allowReserved` based on value of `in`.
···
     irParameter.required = parameter.required;
   }
 
-  // Copy extension fields
-  for (const key in parameter) {
-    if (key.startsWith('x-')) {
-      (irParameter as unknown as Record<string, unknown>)[key] =
-        parameter[key as keyof ParameterObject];
-    }
-  }
+  parseExtensions({
+    source: parameter,
+    target: irParameter,
+  });
 
   return irParameter;
 };

packages/openapi-ts/src/openApi/3.0.x/parser/schema.ts

···
   return irSchema;
 };
 
-const parseExtensions = ({
-  irSchema,
-  schema,
+export const parseExtensions = <T extends Record<string, unknown>>({
+  source,
+  target,
 }: {
-  irSchema: IR.SchemaObject;
-  schema: SchemaObject;
+  source: T;
+  target: Record<string, unknown>;
 }) => {
-  // Copy all x-* extension fields from the source schema to the IR schema
-  for (const key in schema) {
+  for (const key in source) {
     if (key.startsWith('x-')) {
-      (irSchema as unknown as Record<string, unknown>)[key] =
-        schema[key as keyof SchemaObject];
+      target[key] = source[key];
     }
   }
 };
···
   });
 
   parseExtensions({
-    irSchema,
-    schema,
+    source: schema,
+    target: irSchema,
   });
 
   return irSchema;

packages/openapi-ts/src/openApi/3.0.x/types/spec.d.ts

···
  * TODO: examples
  */
 export interface OperationObject {
-  /**
-   * OpenAPI extension fields (x-*) from the original operation.
-   * Specification Extensions may be used to add additional metadata.
-   */
   [extension: `x-${string}`]: unknown;
   /**
    * A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#callback-object Callback Object} that describes a request that may be initiated by the API provider and the expected responses.
···
  * TODO: examples
  */
 export interface ParameterObject {
-  /**
-   * OpenAPI extension fields (x-*) from the original parameter.
-   * Specification Extensions may be used to add additional metadata.
-   */
   [extension: `x-${string}`]: unknown;
   /**
    * If `true`, clients MAY pass a zero-length string value in place of parameters that would otherwise be omitted entirely, which the server SHOULD interpret as the parameter being unused. Default value is `false`. If {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#parameter-style `style`} is used, and if {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#style-examples behavior is _n/a_ (cannot be serialized)}, the value of `allowEmptyValue` SHALL be ignored. Interactions between this field and the parameter's {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#schema-object Schema Object} are implementation-defined. This field is valid only for `query` parameters. Use of this field is NOT RECOMMENDED, and it is likely to be removed in a later revision.
···
  * TODO: content, examples
  */
 export interface SchemaObject extends EnumExtensions {
-  /**
-   * OpenAPI extension fields (x-*) from the original schema.
-   * Specification Extensions may be used to add additional metadata.
-   */
   [extension: `x-${string}`]: unknown;
   /**
    * The value of "additionalProperties" MUST be a boolean or a schema.

packages/openapi-ts/src/openApi/3.1.x/parser/operation.ts

···
     operation,
   });
 
-  // Copy extension fields
-  for (const key in operation) {
-    if (key.startsWith('x-')) {
-      (irOperation as unknown as Record<string, unknown>)[key] =
-        operation[key as keyof Operation];
-    }
-  }
+  parseExtensions({
+    source: operation,
+    target: irOperation,
+  });
 
   return irOperation;
 };

packages/openapi-ts/src/openApi/3.1.x/parser/parameter.ts

···
     irParameter.required = parameter.required;
   }
 
-  // Copy extension fields
-  for (const key in parameter) {
-    if (key.startsWith('x-')) {
-      (irParameter as unknown as Record<string, unknown>)[key] =
-        parameter[key as keyof ParameterObject];
-    }
-  }
+  parseExtensions({
+    source: parameter,
+    target: irParameter,
+  });
 
   return irParameter;
 };

packages/openapi-ts/src/openApi/3.1.x/parser/schema.ts

···
   return irSchema;
 };
 
-const parseExtensions = ({
-  irSchema,
-  schema,
+export const parseExtensions = <T extends Record<string, unknown>>({
+  source,
+  target,
 }: {
-  irSchema: IR.SchemaObject;
-  schema: SchemaObject;
+  source: T;
+  target: Record<string, unknown>;
 }) => {
-  // Copy all x-* extension fields from the source schema to the IR schema
-  for (const key in schema) {
+  for (const key in source) {
     if (key.startsWith('x-')) {
-      (irSchema as unknown as Record<string, unknown>)[key] =
-        schema[key as keyof SchemaObject];
+      target[key] = source[key];
     }
   }
 };
···
   });
 
   parseExtensions({
-    irSchema,
-    schema,
+    source: schema,
+    target: irSchema,
   });
 
   return irSchema;

packages/openapi-ts/src/openApi/3.1.x/types/json-schema-draft-2020-12.d.ts

···
     StringKeywords,
     EnumExtensions,
     OpenApiSchemaExtensions {
-  /**
-   * OpenAPI extension fields (x-*) from the original schema.
-   * Specification Extensions may be used to add additional metadata.
-   */
   [extension: `x-${string}`]: unknown;
   /**
    * The `$comment` {@link https://json-schema.org/learn/glossary#keyword keyword} is strictly intended for adding comments to a schema. Its value must always be a string. Unlike the annotations `title`, `description`, and `examples`, JSON schema {@link https://json-schema.org/learn/glossary#implementation implementations} aren't allowed to attach any meaning or behavior to it whatsoever, and may even strip them at any time. Therefore, they are useful for leaving notes to future editors of a JSON schema, but should not be used to communicate to users of the schema.

packages/openapi-ts/src/openApi/3.1.x/types/spec.d.ts

···
  * ```
  */
 export interface OperationObject {
-  /**
-   * OpenAPI extension fields (x-*) from the original operation.
-   * Specification Extensions may be used to add additional metadata.
-   */
   [extension: `x-${string}`]: unknown;
   /**
    * A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#callback-object Callback Object} that describes a request that may be initiated by the API provider and the expected responses.
···
  * ```
  */
 export interface ParameterObject {
-  /**
-   * OpenAPI extension fields (x-*) from the original parameter.
-   * Specification Extensions may be used to add additional metadata.
-   */
   [extension: `x-${string}`]: unknown;
   /**
    * Sets the ability to pass empty-valued parameters. This is valid only for `query` parameters and allows sending a parameter with an empty value. Default value is `false`. If {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterStyle `style`} is used, and if behavior is `n/a` (cannot be serialized), the value of `allowEmptyValue` SHALL be ignored. Use of this property is NOT RECOMMENDED, as it is likely to be removed in a later revision.