fix(parser): add meta and version options to input.patch

Author: mrlubos

.changeset/strong-donkeys-give.md

@@ -0,0 +1,5 @@
+---
+'@hey-api/openapi-ts': patch
+---
+
+fix(parser): add `meta` and `version` options to input.patch

packages/openapi-ts-tests/test/openapi-ts.config.ts

@@ -42,6 +42,9 @@ export default defineConfig(() => {
       // pagination: {
       //   keywords: ['aa'],
       // },
+      // patch: {
+      //   version: () => '3.1.1',
+      // },
       // path: {
       //   components: {},
       //   info: {

packages/openapi-ts/src/openApi/2.0.x/index.ts

@@ -1,8 +1,9 @@
 export { parseV2_0_X } from './parser';
 export type { OpenApiV2_0_X } from './types/spec';
 
-import type { SchemaObject } from './types/spec';
+import type { InfoObject, SchemaObject } from './types/spec';
 
 export interface OpenApiV2_0_XTypes {
+  InfoObject: InfoObject;
   SchemaObject: SchemaObject;
 }

packages/openapi-ts/src/openApi/3.0.x/index.ts

@@ -2,6 +2,7 @@ export { parseV3_0_X } from './parser';
 export type { OpenApiV3_0_X } from './types/spec';
 
 import type {
+  InfoObject,
   ParameterObject,
   ReferenceObject,
   RequestBodyObject,
@@ -10,6 +11,7 @@ import type {
 } from './types/spec';
 
 export interface OpenApiV3_0_XTypes {
+  InfoObject: InfoObject;
   ParameterObject: ParameterObject;
   ReferenceObject: ReferenceObject;
   RequestBodyObject: RequestBodyObject;

packages/openapi-ts/src/openApi/3.1.x/index.ts

@@ -2,6 +2,7 @@ export { parseV3_1_X } from './parser';
 export type { OpenApiV3_1_X } from './types/spec';
 
 import type {
+  InfoObject,
   ParameterObject,
   ReferenceObject,
   RequestBodyObject,
@@ -10,6 +11,7 @@ import type {
 } from './types/spec';
 
 export interface OpenApiV3_1_XTypes {
+  InfoObject: InfoObject;
   ParameterObject: ParameterObject;
   ReferenceObject: ReferenceObject;
   RequestBodyObject: RequestBodyObject;

packages/openapi-ts/src/openApi/shared/utils/__tests__/patch.test.ts

@@ -383,6 +383,38 @@ describe('patchOpenApiSpec', () => {
         type: 'string',
       });
     });
+
+    it('applies meta patch function', () => {
+      const metaFn = vi.fn((meta) => {
+        meta.title = 'Changed Title';
+      });
+      const spec: OpenApi.V3_1_X = {
+        ...specMetadataV3,
+      };
+      patchOpenApiSpec({
+        patchOptions: {
+          meta: metaFn,
+        },
+        spec,
+      });
+      expect(metaFn).toHaveBeenCalledOnce();
+      expect(spec.info.title).toBe('Changed Title');
+    });
+
+    it('applies version patch function', () => {
+      const versionFn = vi.fn((version) => `patched-${version}`);
+      const spec: OpenApi.V3_1_X = {
+        ...specMetadataV3,
+      };
+      patchOpenApiSpec({
+        patchOptions: {
+          version: versionFn,
+        },
+        spec,
+      });
+      expect(versionFn).toHaveBeenCalledOnce();
+      expect(spec.openapi).toBe('patched-3.1.0');
+    });
   });
 
   describe('OpenAPI v2', () => {
@@ -542,6 +574,38 @@ describe('patchOpenApiSpec', () => {
         type: 'string',
       });
     });
+
+    it('applies meta patch function', () => {
+      const metaFn = vi.fn((meta) => {
+        meta.title = 'Changed Title';
+      });
+      const spec: OpenApi.V2_0_X = {
+        ...specMetadataV2,
+      };
+      patchOpenApiSpec({
+        patchOptions: {
+          meta: metaFn,
+        },
+        spec,
+      });
+      expect(metaFn).toHaveBeenCalledOnce();
+      expect(spec.info.title).toBe('Changed Title');
+    });
+
+    it('applies version patch function', () => {
+      const versionFn = vi.fn((version) => `patched-${version}`);
+      const spec: OpenApi.V2_0_X = {
+        ...specMetadataV2,
+      };
+      patchOpenApiSpec({
+        patchOptions: {
+          version: versionFn,
+        },
+        spec,
+      });
+      expect(versionFn).toHaveBeenCalledOnce();
+      expect(spec.swagger).toBe('patched-2.0');
+    });
   });
 
   describe('real-world usage', () => {

packages/openapi-ts/src/openApi/shared/utils/patch.ts

@@ -15,7 +15,15 @@ export const patchOpenApiSpec = ({
   const spec = _spec as OpenApi.V2_0_X | OpenApi.V3_0_X | OpenApi.V3_1_X;
 
   if ('swagger' in spec) {
-    if (spec.definitions && patchOptions?.schemas) {
+    if (patchOptions.version && spec.swagger) {
+      spec.swagger = patchOptions.version(spec.swagger) as typeof spec.swagger;
+    }
+
+    if (patchOptions.meta && spec.info) {
+      patchOptions.meta(spec.info);
+    }
+
+    if (patchOptions.schemas && spec.definitions) {
       for (const key in patchOptions.schemas) {
         const patchFn = patchOptions.schemas[key]!;
         const schema = spec.definitions[key];
@@ -27,8 +35,26 @@ export const patchOpenApiSpec = ({
     return;
   }
 
+  if (patchOptions.version && spec.openapi) {
+    spec.openapi = patchOptions.version(spec.openapi) as typeof spec.openapi;
+  }
+
+  if (patchOptions.meta && spec.info) {
+    patchOptions.meta(spec.info);
+  }
+
   if (spec.components) {
-    if (spec.components.parameters && patchOptions.parameters) {
+    if (patchOptions.schemas && spec.components.schemas) {
+      for (const key in patchOptions.schemas) {
+        const patchFn = patchOptions.schemas[key]!;
+        const schema = spec.components.schemas[key];
+        if (schema && typeof schema === 'object') {
+          patchFn(schema);
+        }
+      }
+    }
+
+    if (patchOptions.parameters && spec.components.parameters) {
       for (const key in patchOptions.parameters) {
         const patchFn = patchOptions.parameters[key]!;
         const schema = spec.components.parameters[key];
@@ -38,7 +64,7 @@ export const patchOpenApiSpec = ({
       }
     }
 
-    if (spec.components.requestBodies && patchOptions.requestBodies) {
+    if (patchOptions.requestBodies && spec.components.requestBodies) {
       for (const key in patchOptions.requestBodies) {
         const patchFn = patchOptions.requestBodies[key]!;
         const schema = spec.components.requestBodies[key];
@@ -48,7 +74,7 @@ export const patchOpenApiSpec = ({
       }
     }
 
-    if (spec.components.responses && patchOptions.responses) {
+    if (patchOptions.responses && spec.components.responses) {
       for (const key in patchOptions.responses) {
         const patchFn = patchOptions.responses[key]!;
         const schema = spec.components.responses[key];
@@ -57,15 +83,5 @@ export const patchOpenApiSpec = ({
         }
       }
     }
-
-    if (spec.components.schemas && patchOptions?.schemas) {
-      for (const key in patchOptions.schemas) {
-        const patchFn = patchOptions.schemas[key]!;
-        const schema = spec.components.schemas[key];
-        if (schema && typeof schema === 'object') {
-          patchFn(schema);
-        }
-      }
-    }
   }
 };

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

@@ -10,6 +10,14 @@ export namespace OpenApi {
   export type V3_1_X = OpenApiV3_1_X;
 }
 
+export namespace OpenApiMetaObject {
+  export type V2_0_X = OpenApiV2_0_XTypes['InfoObject'];
+
+  export type V3_0_X = OpenApiV3_0_XTypes['InfoObject'];
+
+  export type V3_1_X = OpenApiV3_1_XTypes['InfoObject'];
+}
+
 export namespace OpenApiParameterObject {
   export type V3_0_X =
     | OpenApiV3_0_XTypes['ParameterObject']

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

@@ -1,4 +1,5 @@
 import type {
+  OpenApiMetaObject,
   OpenApiParameterObject,
   OpenApiRequestBodyObject,
   OpenApiResponseObject,
@@ -246,12 +247,43 @@ export interface Filters {
 }
 
 export interface Patch {
+  /**
+   * Patch the OpenAPI meta object in place. Useful for modifying general metadata such as title, description, version, or custom fields before further processing.
+   *
+   * @param meta The OpenAPI meta object for the current version.
+   */
+  meta?: (
+    meta:
+      | OpenApiMetaObject.V2_0_X
+      | OpenApiMetaObject.V3_0_X
+      | OpenApiMetaObject.V3_1_X,
+  ) => void;
+  /**
+   * Patch OpenAPI parameters in place. The key is the parameter name, and the function receives the parameter object to modify directly.
+   *
+   * @example
+   * parameters: {
+   *   limit: (parameter) => {
+   *     parameter.schema.type = 'integer';
+   *   }
+   * }
+   */
   parameters?: Record<
     string,
     (
       parameter: OpenApiParameterObject.V3_0_X | OpenApiParameterObject.V3_1_X,
     ) => void
   >;
+  /**
+   * Patch OpenAPI request bodies in place. The key is the request body name, and the function receives the request body object to modify directly.
+   *
+   * @example
+   * requestBodies: {
+   *   CreateUserRequest: (requestBody) => {
+   *     requestBody.required = true;
+   *   }
+   * }
+   */
   requestBodies?: Record<
     string,
     (
@@ -260,6 +292,16 @@ export interface Patch {
         | OpenApiRequestBodyObject.V3_1_X,
     ) => void
   >;
+  /**
+   * Patch OpenAPI responses in place. The key is the response name, and the function receives the response object to modify directly.
+   *
+   * @example
+   * responses: {
+   *   NotFound: (response) => {
+   *     response.description = 'Resource not found.';
+   *   }
+   * }
+   */
   responses?: Record<
     string,
     (
@@ -303,6 +345,17 @@ export interface Patch {
         | OpenApiSchemaObject.V3_1_X,
     ) => void
   >;
+  /**
+   * Patch the OpenAPI version string. The function receives the current version and should return the new version string.
+   * Useful for normalizing or overriding the version value before further processing.
+   *
+   * @param version The current OpenAPI version string.
+   * @returns The new version string to use.
+   *
+   * @example
+   * version: (version) => version.replace(/^v/, '')
+   */
+  version?: (version: string) => string;
 }
 
 export interface Watch {