Merge pull request #916 from postmanlabs/release/v5.6.0

Release version v5.6.0

Author: AyushShri

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+## [v5.6.0] - 2025-11-28
+
 ## [v5.5.0] - 2025-11-21
 
 ## [v5.4.1] - 2025-11-17
@@ -681,7 +683,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/v5.5.0...HEAD
+[Unreleased]: https://github.com/postmanlabs/openapi-to-postman/compare/v5.6.0...HEAD
+
+[v5.6.0]: https://github.com/postmanlabs/openapi-to-postman/compare/v5.5.0...v5.6.0
 
 [v5.5.0]: https://github.com/postmanlabs/openapi-to-postman/compare/v5.4.1...v5.5.0
 

libV2/helpers/collection/generateSkeletionTreeFromOpenAPI.js

@@ -1,5 +1,6 @@
 let _ = require('lodash'),
   Graph = require('graphlib').Graph,
+  { resolveRefFromSchema } = require('../../schemaUtils'),
 
   PATH_WEBHOOK = 'path~webhook',
   ALLOWED_HTTP_METHODS = {
@@ -14,8 +15,7 @@ let _ = require('lodash'),
     trace: true
   },
 
-
-  _generateTreeFromPathsV2 = function (openapi, { includeDeprecated }) {
+  _generateTreeFromPathsV2 = function (context, openapi, { includeDeprecated }) {
     /**
      * We will create a unidirectional graph
      */
@@ -51,6 +51,10 @@ let _ = require('lodash'),
       if (pathSplit.length === 1) {
         let methods = openapi.paths[completePath];
 
+        if (methods && methods.$ref) {
+          methods = resolveRefFromSchema(context, methods.$ref);
+        }
+
         _.forEach(methods, function (data, method) {
           if (!ALLOWED_HTTP_METHODS[method]) {
             return;
@@ -100,6 +104,10 @@ let _ = require('lodash'),
           if ((index + 1) === pathSplit.length) {
             let methods = openapi.paths[completePath];
 
+            if (methods && methods.$ref) {
+              methods = resolveRefFromSchema(context, methods.$ref);
+            }
+
             _.forEach(methods, function (data, method) {
               if (!ALLOWED_HTTP_METHODS[method]) {
                 return;
@@ -176,7 +184,7 @@ let _ = require('lodash'),
     return tree;
   },
 
-  _generateTreeFromTags = function (openapi, { includeDeprecated }) {
+  _generateTreeFromTags = function (context, openapi, { includeDeprecated }) {
     let tree = new Graph(),
 
       tagDescMap = _.reduce(openapi.tags, function (acc, data) {
@@ -216,6 +224,10 @@ let _ = require('lodash'),
     });
 
     _.forEach(openapi.paths, function (methods, path) {
+      if (methods && methods.$ref) {
+        methods = resolveRefFromSchema(context, methods.$ref);
+      }
+
       _.forEach(methods, function (data, method) {
         if (!ALLOWED_HTTP_METHODS[method]) {
           return;
@@ -284,12 +296,13 @@ let _ = require('lodash'),
 
   /**
    * Generates tree structure with nested folders based on tag order
+   * @param {Object} context - Global context object
    * @param {Object} openapi - OpenAPI specification
    * @param {Object} options - Generation options
    * @param {boolean} options.includeDeprecated - Whether to include deprecated operations
    * @returns {Object} - Graph tree with nested folder structure
    */
-  _generateTreeFromNestedTags = function (openapi, { includeDeprecated }) {
+  _generateTreeFromNestedTags = function (context, openapi, { includeDeprecated }) {
     let tree = new Graph(),
 
       tagDescMap = _.reduce(openapi.tags, function (acc, data) {
@@ -345,6 +358,10 @@ let _ = require('lodash'),
     };
 
     _.forEach(openapi.paths, function (methods, path) {
+      if (methods && methods.$ref) {
+        methods = resolveRefFromSchema(context, methods.$ref);
+      }
+
       _.forEach(methods, function (data, method) {
         if (!ALLOWED_HTTP_METHODS[method]) {
           return;
@@ -400,7 +417,7 @@ let _ = require('lodash'),
     return tree;
   },
 
-  _generateWebhookEndpoints = function (openapi, tree, { includeDeprecated }) {
+  _generateWebhookEndpoints = function (context, openapi, tree, { includeDeprecated }) {
     if (!_.isEmpty(openapi.webhooks)) {
       tree.setNode(`${PATH_WEBHOOK}:folder`, {
         type: 'webhook~folder',
@@ -416,6 +433,10 @@ let _ = require('lodash'),
     }
 
     _.forEach(openapi.webhooks, function (methodData, path) {
+      if (methodData && methodData.$ref) {
+        methodData = resolveRefFromSchema(context, methodData.$ref);
+      }
+
       _.forEach(methodData, function (data, method) {
         /**
          * include deprecated handling.
@@ -441,35 +462,37 @@ let _ = require('lodash'),
 /**
  * Used to generate a tree skeleton for the openapi which will be a collection
  *
+ * @param  {Object} context - Global context object
  * @param  {Object} openapi - openapi schema paths in question
  * @param  {String} stratergy='PATHS'
  *
  * @returns {Object} - tree format
  */
-module.exports = function (openapi, { folderStrategy, includeWebhooks, includeDeprecated, nestedFolderHierarchy }) {
+module.exports = function (context, openapi,
+  { folderStrategy, includeWebhooks, includeDeprecated, nestedFolderHierarchy }) {
   let skeletonTree;
 
   switch (folderStrategy) {
     case 'tags':
       if (nestedFolderHierarchy) {
-        skeletonTree = _generateTreeFromNestedTags(openapi, { includeDeprecated });
+        skeletonTree = _generateTreeFromNestedTags(context, openapi, { includeDeprecated });
       }
       else {
-        skeletonTree = _generateTreeFromTags(openapi, { includeDeprecated });
+        skeletonTree = _generateTreeFromTags(context, openapi, { includeDeprecated });
       }
 
       break;
 
     case 'paths':
-      skeletonTree = _generateTreeFromPathsV2(openapi, { includeDeprecated });
+      skeletonTree = _generateTreeFromPathsV2(context, openapi, { includeDeprecated });
       break;
 
     default:
       throw new Error('generateSkeletonTreeFromOpenAPI~folderStrategy not valid');
   }
 
   if (includeWebhooks) {
-    skeletonTree = _generateWebhookEndpoints(openapi, skeletonTree, { includeDeprecated });
+    skeletonTree = _generateWebhookEndpoints(context, openapi, skeletonTree, { includeDeprecated });
   }
 
   return skeletonTree;

libV2/index.js

@@ -14,7 +14,7 @@ const _ = require('lodash'),
   OpenApiErr = require('../lib/error'),
   { validateTransaction, getMissingSchemaEndpoints } = require('./validationUtils');
 
-const { resolvePostmanRequest } = require('./schemaUtils');
+const { resolvePostmanRequest, resolveRefFromSchema } = require('./schemaUtils');
 const { generateRequestItemObject, fixPathVariablesInUrl } = require('./utils');
 
 module.exports = {
@@ -23,7 +23,7 @@ module.exports = {
      * Start generating the Bare bone tree that should exist for the schema
      */
 
-    let collectionTree = generateSkeletonTreeFromOpenAPI(context.openapi, context.computedOptions);
+    let collectionTree = generateSkeletonTreeFromOpenAPI(context, context.openapi, context.computedOptions);
 
     /**
      * Do post order traversal so we get the request nodes first and generate the request object
@@ -92,11 +92,16 @@ module.exports = {
           let request = {},
             collectionVariables = [],
             requestObject = {},
-            requestTypesObject = {};
+            requestTypesObject = {},
+            pathItem = context.openapi.paths[node.meta.path];
+
+          if (pathItem && pathItem.$ref) {
+            pathItem = resolveRefFromSchema(context, pathItem.$ref);
+          }
 
           try {
             ({ request, collectionVariables, requestTypesObject } = resolvePostmanRequest(context,
-              context.openapi.paths[node.meta.path],
+              pathItem,
               node.meta.path,
               node.meta.method
             ));
@@ -166,7 +171,12 @@ module.exports = {
           // generate the request form the node
           let request = {},
             collectionVariables = [],
-            requestObject = {};
+            requestObject = {},
+            webhookPathItem = context.openapi.webhooks[node.meta.path];
+
+          if (webhookPathItem && webhookPathItem.$ref) {
+            webhookPathItem = resolveRefFromSchema(context, webhookPathItem.$ref);
+          }
 
           // TODO: Figure out a proper fix for this
           if (node.meta.method === 'parameters') {
@@ -175,7 +185,7 @@ module.exports = {
 
           try {
             ({ request, collectionVariables } = resolvePostmanRequest(context,
-              context.openapi.webhooks[node.meta.path],
+              webhookPathItem,
               node.meta.path,
               node.meta.method
             ));

libV2/schemaUtils.js

@@ -303,6 +303,8 @@ let QUERYPARAM = 'query',
     const { specComponents } = context,
       { stackLimit } = context.computedOptions;
 
+    context.schemaCache = context.schemaCache || {};
+
     if (stackDepth >= getRefStackLimit(stackLimit)) {
       return { value: ERR_TOO_MANY_LEVELS };
     }
@@ -721,7 +723,7 @@ let QUERYPARAM = 'query',
 
         schema.properties = resolvedSchemaProps;
       }
-      
+
       schema.type = schema.type || SCHEMA_TYPES.object;
     }
     // If schema is of type array
@@ -833,10 +835,10 @@ let QUERYPARAM = 'query',
 
     if (resolvedSchema.type === 'object') {
       const schemaDetails = {
-          description: resolvedSchema.description,
-          title: resolvedSchema.title,
-          type: resolvedSchema.type
-        };
+        description: resolvedSchema.description,
+        title: resolvedSchema.title,
+        type: resolvedSchema.type
+      };
 
       // Only include properties if they exist in the original schema
       if (resolvedSchema.hasOwnProperty('properties')) {

libV2/validationUtils.js

@@ -2721,6 +2721,10 @@ module.exports = {
     );
 
     _.forEach(schemaPaths, (schemaPathObj, schemaPath) => {
+      if (schemaPathObj && schemaPathObj.$ref) {
+        schemaPathObj = resolveRefFromSchema(context, schemaPathObj.$ref);
+      }
+
       _.forEach(_.keys(schemaPathObj), (pathKey) => {
         schemaJsonPath = `$.paths[${schemaPath}].${_.toLower(pathKey)}`;
         let operationItem = _.get(schemaPathObj, pathKey) || {},

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "openapi-to-postmanv2",
-  "version": "5.5.0",
+  "version": "5.6.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

@@ -0,0 +1,67 @@
+openapi: "3.1.0"
+info:
+  version: 1.0.0
+  title: Nested Path Item References Test
+  description: API with nested path item references to test recursive resolution
+
+paths:
+  /users:
+    $ref: "#/components/pathItems/UsersPathRef"  # Level 1 ref -> Level 2 ref -> actual path item
+  
+  /products:
+    $ref: "#/components/pathItems/ProductsPath"  # Direct ref to actual path item
+  
+  /orders:
+    get:
+      summary: Get orders
+      operationId: getOrders
+      responses:
+        '200':
+          description: OK
+
+components:
+  pathItems:
+    # This is a nested reference - points to another ref
+    UsersPathRef:
+      $ref: "#/components/pathItems/UsersPathLevel2"
+    
+    # This is the second level - points to the actual path item
+    UsersPathLevel2:
+      $ref: "#/components/pathItems/UsersPathActual"
+    
+    # This is the actual path item with operations
+    UsersPathActual:
+      get:
+        summary: List users
+        operationId: listUsers
+        responses:
+          '200':
+            description: A list of users
+      post:
+        summary: Create user
+        operationId: createUser
+        responses:
+          '201':
+            description: User created
+      delete:
+        summary: Delete user
+        operationId: deleteUser
+        responses:
+          '204':
+            description: User deleted
+    
+    # Direct path item (no nesting)
+    ProductsPath:
+      get:
+        summary: Get products
+        operationId: getProducts
+        responses:
+          '200':
+            description: A list of products
+      post:
+        summary: Create product
+        operationId: createProduct
+        responses:
+          '201':
+            description: Product created
+