Conversion creates a different file structure

[eo33]

Hey there 👋 I have an OAS 3.0 and would like to convert it to a Postman collection. The openapi-to-postman command works, and the OAS file was successfully converted to a Postman collection, but the collection generated follows a different file structure.

What happened?

This OAS file was successfully converted to this Postman collection file. But the collection follows this folder structure:

Account/
├── auth/
│   ├── register/
│   │	├── POST Register an Account
│   ├── login/
│   │	├── POST Get an API key
│   ├── validate
│   │	├── GET Validate API key
├── users/
│   ├── get_all/
│   │	├──{page}
│   │	│   ├── GET Get Users
│   ├── edit/
│   │	├── POST Edit User Details

This is what it looks like when rendered with Postman:

What do I expect to happen?

The folder structure of the postman collection to follow this:

Account
├── POST Register an Account
├── POST Get an API key
├── POST Validate API Key
├── GET Get Users
├── POST Edit User Details

This is what it looks like in Postman:

Here's the Postman collection file.

[thim81]

hi @eo33

the openapi-to-postman conversion has a number of options.

Potentially you can change the folderStrategy option to "Tags", to get a different grouping result:

[HabiburRahmaan]

When converting an OAS 3.0 specification to a Postman collection using tools like openapi-to-postman, the generated collection creates nested folders based on URL path segments (e.g., /auth/register becomes Account > auth > register). The user expects a flat structure with all endpoints directly under the parent folder (e.g., all methods under Account), avoiding unnecessary nesting.

Root Cause
Most OAS-to-Postman tools (including openapi-to-postman) default to mirroring the API’s URL path hierarchy as folders. For example:

Path /auth/register → Folders auth > register.

Path /users/{page} → Folders users > {page}.

This behavior is standard but often clashes with user preferences for simpler, flatter collections.

Solutions

1. Use Converter Options to Flatten Structure
   Many tools support flags to override folder generation. For example:

openapi-to-postman: Use the --folderStrategy flag to group endpoints by tags instead of paths.

openapi2postmanv2 -s oas.yaml -o postman.json -O folderStrategy=Tags
Prerequisite: Ensure your OAS file defines tags for endpoints you want to group.

postman-code-generators: Use Postman’s built to customize folder logic during import.

2. Modify Your OAS Specification
   Adjust your OpenAPI spec to influence the output:

Remove redundant path segments: Simplify paths (e.g., use /register instead of /auth/register).

Use x-postman-meta: Some tools allow custom metadata to control grouping.

paths:
/auth/register:
post:
x-postman-meta:
folder: Account
3. Post-Conversion Scripting
Write a script to flatten the Postman collection post-conversion. Example (Node.js):

const fs = require('fs');
const collection = JSON.parse(fs.readFileSync('postman.json'));

// Flatten all requests to the root folder
collection.item.forEach((folder) => {
if (folder.item) {
collection.item.push(...folder.item); // Move nested items to root
}
});

fs.writeFileSync('flattened-postman.json', JSON.stringify(collection));
Simpler Alternative: Use Apyhub’s API Converter
For a zero-config, flat Postman collection without nested folders:
Apyhub’s API Converter generates clean, minimally nested collections by default.

Steps:

Upload your OAS file.

Set output_format=postman.

(Optional) Use group_by=tags if you prefer tag-based grouping.

[VShingala]

@eo33 @HabiburRahmaan As mentioned by @thim81, you can make use of folderStrategy option with Tags as value to generate the collection with correct folder organisation. This option will make use of tags defined in your spec to group the endpoints.

Here's how the generated collection look like using Tags as value for folderStrategy option for the provided OpenAPI specification.

Do let us know if this solves your issue or give your feedback on the suggested approach if it's missing anything.

[shamasis]

It almost feels like PostBot should do this conversion. Then the structure, names and descriptions would be interesting to see where it goes. Just an idea 😛 @abhijitkane