Merge pull request #956 from postmanlabs/release/v6.3.0

Release version v6.3.0

Author: AyushShri

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+## [v6.3.0] - 2026-07-07
+
 ## [v6.2.0] - 2026-06-29
 
 ## [v6.1.0] - 2026-06-09
@@ -695,7 +697,9 @@ Newer releases follow the [Keep a Changelog](https://keepachangelog.com/en/1.0.0
 
 -   Base release
 
-[Unreleased]: https://github.com/postmanlabs/openapi-to-postman/compare/v6.2.0...HEAD
+[Unreleased]: https://github.com/postmanlabs/openapi-to-postman/compare/v6.3.0...HEAD
+
+[v6.3.0]: https://github.com/postmanlabs/openapi-to-postman/compare/v6.2.0...v6.3.0
 
 [v6.2.0]: https://github.com/postmanlabs/openapi-to-postman/compare/v6.1.0...v6.2.0
 

README.md

@@ -142,10 +142,18 @@ $ openapi2postmanv2 -s spec.yaml --sync collection.json --sync-options-config sy
 **sync-options.json:**
 ```json
 {
-  "syncExamples": true
+  "syncExamples": true,
+  "deleteOrphanedRequests": false
 }
 ```
 
+#### Available Sync Options
+
+| id | type | default | description |
+|---|---|---|---|
+| `syncExamples` | boolean | `false` | Whether to sync response examples from the OpenAPI specification to the collection. When enabled, response examples in the spec are synced with existing collection responses. |
+| `deleteOrphanedRequests` | boolean | `false` | Whether to delete requests and folders that exist in the collection but no longer exist in the OpenAPI specification. When disabled (default), such orphans are preserved to avoid unintentional data loss. |
+
 For a complete list of sync options and their usage, see [SYNC_OPTIONS.md](/SYNC_OPTIONS.md)
 
 
@@ -314,7 +322,8 @@ const fs = require('fs'),
   existingCollection = JSON.parse(fs.readFileSync('collection.json', {encoding: 'UTF8'}));
 
 const syncOptions = {
-  syncExamples: true
+  syncExamples: true,
+  deleteOrphanedRequests: false
 };
 
 Converter.syncCollection(

SYNC_OPTIONS.md

@@ -7,6 +7,7 @@ This document describes the available options for syncing OpenAPI specifications
 | id | type | default | description | version |
 |---|---|---|---|---|
 | syncExamples | boolean | false | Whether to sync response examples from the OpenAPI specification to the collection. When enabled, response examples in the spec will be synced with existing collection responses. | v2 |
+| deleteOrphanedRequests | boolean | false | Whether to delete requests and folders that exist in the collection but no longer exist in the OpenAPI specification. When disabled (default), such orphans are preserved to avoid unintentional data loss. | v2 |
 
 ## Usage
 

lib/options.js

@@ -486,6 +486,19 @@ module.exports = {
         usage: ['SYNC'],
         supportedIn: [VERSION20, VERSION30, VERSION31, VERSION32],
         supportedModuleVersion: [MODULE_VERSION.V2]
+      },
+      {
+        name: 'Delete orphaned requests',
+        id: 'deleteOrphanedRequests',
+        type: 'boolean',
+        default: false,
+        description: 'Whether to delete requests and folders that exist in the collection but no longer ' +
+          'exist in the OpenAPI specification. When disabled (default), such orphans are preserved to ' +
+          'avoid unintentional data loss.',
+        external: true,
+        usage: ['SYNC'],
+        supportedIn: [VERSION20, VERSION30, VERSION31, VERSION32],
+        supportedModuleVersion: [MODULE_VERSION.V2]
       }
     ];
 

libV2/SpecificationCollectionSyncing/shared/constants.ts

@@ -43,5 +43,6 @@ export const ALLOWED_AUTH_PARAM_KEYS_BY_TYPE: Record<string, Set<string>> = {
 };
 
 export const DEFAULT_SYNC_OPTIONS: SyncOptions = {
-  syncExamples: false
+  syncExamples: false,
+  deleteOrphanedRequests: false
 };

libV2/SpecificationCollectionSyncing/shared/types.ts

@@ -84,4 +84,10 @@ export interface AuthMergeResult {
 
 export type SyncOptions = {
   syncExamples: boolean;
+  /**
+   * When true, requests (and folders) that exist in the collection but no longer exist in the
+   * specification are removed during spec -> collection syncing.
+   * When false (default), such orphans are preserved to avoid unintentional data loss.
+   */
+  deleteOrphanedRequests?: boolean;
 };

libV2/SpecificationCollectionSyncing/spec-to-collection/index.ts

@@ -164,6 +164,19 @@ export function syncCollection(
     }
   });
 
+  // When opted in, remove orphans: requests and folders that exist in the collection but no longer
+  // exist in the latest spec-derived state. Matched folders are pruned recursively above via the
+  // sync loop (mergedOptions is propagated), so here we only drop unmatched items at this level.
+  if (mergedOptions.deleteOrphanedRequests) {
+    currentCollectionState.items.remove((item: Item | ItemGroup<Item>) => {
+      if (item instanceof ItemGroup) {
+        return !findFolderItemByName(latestCollectionState, item.name);
+      }
+
+      return !findRequestItemByPathAndMethod(latestCollectionState, getRequestIdentifier(item));
+    }, currentCollectionState);
+  }
+
   currentCollectionState.description = latestCollectionState.description;
 
   const existingCollectionAuth = _.cloneDeep(currentCollectionState?.auth?.toJSON()) ?? {},

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "openapi-to-postmanv2",
-  "version": "6.2.0",
+  "version": "6.3.0",
   "description": "Convert a given OpenAPI specification to Postman Collection v2.0",
   "homepage": "https://github.com/postmanlabs/openapi-to-postman",
   "bugs": "https://github.com/postmanlabs/openapi-to-postman/issues",

package.json

@@ -30,6 +30,7 @@ module.exports = {
   shouldSyncRequestToFirstResponseOnly: require('./shouldSyncRequestToFirstResponseOnly'),
   shouldPreserveOtherSameCodeResponsesOnRequestSync: require('./shouldPreserveOtherSameCodeResponsesOnRequestSync'),
   shouldPairSameCodeExamplesPositionallyOnSync: require('./shouldPairSameCodeExamplesPositionallyOnSync'),
+  shouldDeleteOrphanRequestsWhenEnabled: require('./shouldDeleteOrphanRequestsWhenEnabled'),
   // Multi-file specification test cases
   multiFileSpecs: require('./multiFileSpecs')
 };