swagger-to-postman-cli 1.0.1

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026, Onur runotr13@gmail.com
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/dist/cli.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import ora from "ora";
+import pc from "picocolors";
+import { generatePostman } from "./index.js";
+const program = new Command();
+program
+    .name("swagger-to-postman")
+    .requiredOption("-i, --input <pathOrUrl>", "Swagger/OpenAPI file or URL")
+    .option("-o, --output <path>", "Output folder", "./output")
+    .option("--sync", "Sync collection to Postman")
+    .action(async (opts) => {
+    const spinner = ora(pc.cyan("Swagger analiz ediliyor...")).start();
+    try {
+        await generatePostman({
+            input: opts.input,
+            output: opts.output,
+            sync: opts.sync,
+        });
+        spinner.succeed(pc.green("Başarıyla tamamlandı!"));
+    }
+    catch (err) {
+        spinner.fail(pc.red(err.message));
+        process.exit(1);
+    }
+});
+program.parse();

package/dist/core/CollectionBuilder.js

@@ -0,0 +1,90 @@
+import sdk from "postman-collection";
+import * as fs from "fs";
+export class CollectionBuilder {
+    collection;
+    constructor(title) {
+        this.collection = new sdk.Collection({
+            info: { name: `${title} - Automated Tests` },
+        });
+    }
+    addRequest(method, urlPath, bodyData, parameters = []) {
+        const queryParams = parameters
+            .filter((p) => p.in === "query")
+            .map((p) => ({
+            key: p.name,
+            value: `{{${p.name}}}`,
+            description: p.description || "",
+        }));
+        const pathVariables = parameters
+            .filter((p) => p.in === "path")
+            .map((p) => ({
+            key: p.name,
+            value: `{{${p.name}}}`,
+            description: p.description || "",
+        }));
+        const requestConfig = {
+            method: method.toUpperCase(),
+            header: [{ key: "Content-Type", value: "application/json" }],
+            url: {
+                host: ["{{baseUrl}}"],
+                path: urlPath
+                    .split("/")
+                    .filter((p) => p !== "")
+                    .map((p) => p.replace(/{/g, ":").replace(/}/g, "")),
+                query: queryParams,
+                variable: pathVariables,
+            },
+        };
+        if (bodyData && Object.keys(bodyData).length > 0) {
+            requestConfig.body = {
+                mode: "raw",
+                raw: JSON.stringify(bodyData, null, 2),
+                options: { raw: { language: "json" } },
+            };
+        }
+        const newItem = new sdk.Item({
+            name: `${method.toUpperCase()} ${urlPath}`,
+            request: requestConfig,
+        });
+        newItem.events.add(new sdk.Event({
+            listen: "test",
+            script: {
+                type: "text/javascript",
+                exec: [
+                    'pm.test("Status code is 200", function () { pm.response.to.have.status(200); });',
+                ],
+            },
+        }));
+        this.collection.items.add(newItem);
+    }
+    setAuthentication(securitySchemes) {
+        if (!securitySchemes)
+            return;
+        const schemeNames = Object.keys(securitySchemes);
+        if (schemeNames.length === 0)
+            return;
+        const scheme = securitySchemes[schemeNames[0]];
+        if (scheme.type === "apiKey") {
+            this.collection.auth = new sdk.RequestAuth({
+                type: "apikey",
+                apikey: [
+                    { key: "key", value: scheme.name, type: "string" },
+                    { key: "value", value: "{{apiKey}}", type: "string" },
+                    { key: "in", value: scheme.in || "header", type: "string" },
+                ],
+            });
+        }
+        else if (scheme.type === "http" && scheme.scheme === "bearer") {
+            this.collection.auth = new sdk.RequestAuth({
+                type: "bearer",
+                bearer: [{ key: "token", value: "{{bearerToken}}", type: "string" }],
+            });
+        }
+    }
+    saveToFile(fileName) {
+        fs.writeFileSync(fileName, JSON.stringify(this.collection.toJSON(), null, 2));
+    }
+    getCollection() {
+        return this.collection;
+    }
+}

package/dist/core/EnvironmentBuilder.js

@@ -0,0 +1,25 @@
+import * as fs from "fs";
+export class EnvironmentBuilder {
+    env;
+    constructor(title) {
+        this.env = {
+            name: `${title} - Env`,
+            values: [],
+            _postman_variable_scope: "environment",
+        };
+    }
+    addVariable(key, value) {
+        const exists = this.env.values.find((v) => v.key === key);
+        if (!exists) {
+            this.env.values.push({
+                key,
+                value,
+                enabled: true,
+                type: "default",
+            });
+        }
+    }
+    saveToFile(fileName) {
+        fs.writeFileSync(fileName, JSON.stringify(this.env, null, 2));
+    }
+}

package/dist/generators/DataFactory.js

@@ -0,0 +1,29 @@
+import { faker } from "@faker-js/faker";
+export class DataFactory {
+    static generate(type, format, fieldName, enumValues) {
+        if (enumValues && enumValues.length > 0)
+            return faker.helpers.arrayElement(enumValues);
+        const lowerFieldName = fieldName?.toLowerCase() || "";
+        if (lowerFieldName.includes("email"))
+            return faker.internet.email();
+        if (lowerFieldName.includes("password"))
+            return faker.internet.password();
+        if (lowerFieldName.includes("url"))
+            return faker.internet.url();
+        if (lowerFieldName.includes("id") && type === "integer")
+            return faker.number.int({ min: 1, max: 999 });
+        switch (type) {
+            case "string":
+                if (format === "date-time")
+                    return faker.date.recent().toISOString();
+                return faker.lorem.word();
+            case "integer":
+            case "number":
+                return faker.number.int({ min: 1, max: 100 });
+            case "boolean":
+                return faker.datatype.boolean();
+            default:
+                return null;
+        }
+    }
+}

package/dist/generators/generate-mock-data.js

@@ -0,0 +1,20 @@
+import { DataFactory } from "./DataFactory.js";
+export function generateMockData(schema, fieldName = "") {
+    if (!schema)
+        return null;
+    const target = schema.schema ? schema.schema : schema;
+    const type = target.type || (target.properties ? "object" : "string");
+    if (type === "array") {
+        const items = target.items || { type: "string" };
+        return [generateMockData(items, fieldName)];
+    }
+    if (type === "object" || target.properties) {
+        const obj = {};
+        const props = target.properties || {};
+        for (const [key, value] of Object.entries(props)) {
+            obj[key] = generateMockData(value, key);
+        }
+        return obj;
+    }
+    return DataFactory.generate(type, target.format, fieldName || target.name || target.title, target.enum);
+}

package/dist/helpers/syncToPostman.js

@@ -0,0 +1,32 @@
+import ora from "ora";
+import pc from "picocolors";
+export async function syncToPostman(collectionData) {
+    const apiKey = process.env.POSTMAN_API_KEY;
+    const collectionId = process.env.COLLECTION_ID;
+    if (!apiKey || !collectionId) {
+        console.log(pc.yellow("\n⚠️ API Key veya Collection ID bulunamadı, senkronizasyon atlandı."));
+        return;
+    }
+    const spinner = ora(pc.cyan("Postman koleksiyonu güncelleniyor...")).start();
+    try {
+        const res = await fetch(`https://api.getpostman.com/collections/${collectionId}`, {
+            method: "PUT",
+            headers: {
+                "X-Api-Key": apiKey,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                collection: collectionData,
+            }),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`${res.status} ${res.statusText} - ${text}`);
+        }
+        spinner.succeed(pc.green("Postman başarıyla güncellendi!"));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        spinner.fail(pc.red("Postman güncellenirken hata: " + message));
+    }
+}

package/dist/index.js

@@ -0,0 +1,58 @@
+import fs from "fs";
+import SwaggerParser from "@apidevtools/swagger-parser";
+import { CollectionBuilder } from "./core/CollectionBuilder.js";
+import { EnvironmentBuilder } from "./core/EnvironmentBuilder.js";
+import { SwaggerService } from "./services/SwaggerService.js";
+import { generateMockData } from "./generators/generate-mock-data.js";
+import { syncToPostman } from "./helpers/syncToPostman.js";
+export async function generatePostman({ input, output = "./output", sync = false, }) {
+    const api = await SwaggerParser.validate(input);
+    const colBuilder = new CollectionBuilder(api.info.title);
+    const envBuilder = new EnvironmentBuilder(api.info.title);
+    const security = SwaggerService.getSecuritySchemes(api);
+    colBuilder.setAuthentication(security);
+    const securityStr = JSON.stringify(security || "");
+    if (securityStr.includes("apiKey"))
+        envBuilder.addVariable("apiKey", "YOUR_KEY");
+    if (securityStr.includes("bearer"))
+        envBuilder.addVariable("bearerToken", "YOUR_TOKEN");
+    envBuilder.addVariable("baseUrl", SwaggerService.getBaseUrl(api));
+    for (const [path, pathItem] of Object.entries(api.paths || {})) {
+        if (!pathItem)
+            continue;
+        for (const method of [
+            "get",
+            "post",
+            "put",
+            "delete",
+            "patch",
+            "options",
+            "head",
+        ]) {
+            const operation = pathItem[method];
+            if (!operation)
+                continue;
+            const parameters = operation.parameters || [];
+            parameters.forEach((param) => {
+                if (param.in !== "body") {
+                    const mockVal = generateMockData(param, param.name);
+                    envBuilder.addVariable(param.name, String(mockVal ?? ""));
+                }
+            });
+            let mockBody = {};
+            const bodySchema = operation.requestBody?.content?.["application/json"]?.schema ||
+                parameters.find((p) => p.in === "body")?.schema;
+            if (bodySchema) {
+                mockBody = generateMockData(bodySchema);
+            }
+            colBuilder.addRequest(method, path, mockBody, parameters);
+        }
+    }
+    if (!fs.existsSync(output))
+        fs.mkdirSync(output, { recursive: true });
+    colBuilder.saveToFile(`${output}/collection.json`);
+    envBuilder.saveToFile(`${output}/environment.json`);
+    if (sync) {
+        await syncToPostman(colBuilder.getCollection());
+    }
+}

package/dist/services/SwaggerService.js

@@ -0,0 +1,14 @@
+export class SwaggerService {
+    static getBaseUrl(api) {
+        if (api.servers && api.servers.length > 0)
+            return api.servers[0].url;
+        if (api.host) {
+            const protocol = (api.schemes && api.schemes[0]) || "https";
+            return `${protocol}://${api.host}${api.basePath || ""}`;
+        }
+        return "http://localhost";
+    }
+    static getSecuritySchemes(api) {
+        return api.components?.securitySchemes || api.securityDefinitions || null;
+    }
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "swagger-to-postman-cli",
+  "version": "1.0.1",
+  "description": "Generate dynamic Postman collections from Swagger/OpenAPI with Faker.js",
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "bin": {
+    "swagger-to-postman": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc && chmod +x dist/cli.js",
+    "start": "npx tsx src/cli.ts",
+    "prepare": "npm run build",
+    "prelink": "npm run build"
+  },
+  "keywords": [
+    "swagger",
+    "openapi",
+    "postman",
+    "faker",
+    "testing",
+    "automation",
+    "mock-data"
+  ],
+  "author": "Onur runotr13@gmail.com",
+  "license": "ISC",
+  "dependencies": {
+    "@apidevtools/swagger-parser": "^12.1.0",
+    "@faker-js/faker": "^10.2.0",
+    "commander": "^14.0.2",
+    "openapi-types": "^12.1.3",
+    "ora": "^9.0.0",
+    "picocolors": "^1.1.1",
+    "postman-collection": "^5.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.8",
+    "@types/postman-collection": "^3.5.11",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}

package/readme.md

@@ -0,0 +1,95 @@
+# Swagger to Postman (CLI Tool) 🚀
+[![Update Postman Collection](https://github.com/runotr13/swagger-to-postman/actions/workflows/postman-sync.yml/badge.svg)](https://github.com/runotr13/swagger-to-postman/actions/workflows/postman-sync.yml)
+![TypeScript](https://img.shields.io/badge/typescript-%23007ACC.svg?style=for-the-badge&logo=typescript&logoColor=white)
+![NodeJS](https://img.shields.io/badge/node.js-6DA55F?style=for-the-badge&logo=node.js&logoColor=white)
+![GitHub Actions](https://img.shields.io/badge/github%20actions-%232671E5.svg?style=for-the-badge&logo=githubactions&logoColor=white)
+
+Generate dynamic, automated Postman collections and environments directly from your Swagger/OpenAPI documentation. This tool leverages **Faker.js** to populate requests with realistic mock data, ensuring a robust and production-ready testing workflow.
+
+---
+
+## 🛠 Features
+
+- **Smart Mocking:** Automatically detects field names like `email`, `name`, `id`, and `password` to generate context-aware data.
+- **Recursive Parsing:** Deeply crawls nested objects and arrays in your Swagger schemas.
+- **Postman SDK:** Built on top of the official `postman-collection` library.
+- **Environment Automation:** Auto-generates `baseUrl` and security variables (API Key, Bearer Token).
+- **CI/CD Ready:** Built-in support for synchronizing collections directly to Postman Cloud.
+
+---
+
+## 📂 Project Structure
+
+The project is organized following the **Single Responsibility Principle**:
+
+```text
+src/
+├── core/               # Postman SDK logic (Collection & Environment)
+├── generators/         # Mock data engine and schema traversal
+├── helpers/            # Utility functions (e.g., Postman Cloud Sync)
+├── services/           # Swagger analysis and business logic
+├── cli.ts              # CLI entry point
+└── index.ts            # Public library API
+```
+
+## 📦 npm Usage
+
+### Run without install
+
+```bash
+npx swagger-to-postman -i ./swagger.json
+```
+
+### Global install
+
+```bash
+npm install -g swagger-to-postman
+swagger-to-postman -i ./swagger.json
+```
+
+### Local dependency
+
+```bash
+npm install swagger-to-postman
+npx swagger-to-postman -i ./swagger.json
+```
+
+## Build and Link locally:
+
+```bash
+npm run build
+npm link
+```
+
+## Development
+
+```bash
+npm run start -- -i ./swagger.json -o ./output
+```
+
+## Running the Tool
+
+```bash
+# Using a local file
+swagger-to-postman -i ./swagger.json -o ./output
+
+# Using a remote URL
+swagger-to-postman -i https://petstore.swagger.io/v2/swagger.json -o ./petstore-output
+```
+
+## 📖 CLI Arguments
+
+| Argument   | Shorthand | Description                                             | Default    |
+| :--------- | :-------- | :------------------------------------------------------ | :--------- |
+| `--input`  | `-i`      | **(Required)** Path to local swagger.json or remote URL | N/A        |
+| `--output` | `-o`      | Target directory for generated files                    | `./output` |
+
+## 📤 Output
+
+The tool generates the following files:
+
+```text
+output/
+├── collection.json     # Postman Collection
+└── environment.json    # Postman Environment
+```