@scalar/postman-to-openapi 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @scalar/postman-to-openapi
+
+## 0.1.0
+
+### Minor Changes
+
+- a0bcd23: hello world :)
+
+### Patch Changes
+
+- Updated dependencies [44a7100]
+  - @scalar/oas-utils@0.2.77

package/README.md

@@ -0,0 +1,33 @@
+# Postman to OpenAPI Converter
+
+[![Version](https://img.shields.io/npm/v/%40scalar/postman-to-openapi)](https://www.npmjs.com/package/@scalar/postman-to-openapi)
+[![Downloads](https://img.shields.io/npm/dm/%40scalar/postman-to-openapi)](https://www.npmjs.com/package/@scalar/postman-to-openapi)
+[![License](https://img.shields.io/npm/l/%40scalar%2Fpostman-to-openapi)](https://www.npmjs.com/package/@scalar/postman-to-openapi)
+[![Discord](https://img.shields.io/discord/1135330207960678410?style=flat&color=5865F2)](https://discord.gg/scalar)
+
+Convert Postman collections to [the open standard OpenAPI](https://github.com/OAI/OpenAPI-Specification). Free the postman!
+
+## Installation
+
+```bash
+npm install @scalar/postman-to-openapi
+```
+
+## Usage
+
+```ts
+import { convert } from '@scalar/postman-to-openapi'
+
+// Free the postman!
+const result = await convert(myPostmanCollection)
+
+console.log(result)
+```
+
+## Community
+
+We are API nerds. You too? Let’s chat on Discord: <https://discord.gg/scalar>
+
+## Thank you!
+
+This package is based on the existing [`postman-to-openapi`](https://github.com/joolfe/postman-to-openapi) by [@joolfe](https://github.com/joolfe). We update the code and adapted it to our use case. You might consider our package the modern successor.

package/dist/convert.d.ts

@@ -0,0 +1,9 @@
+import type { OpenAPIV3_1 } from '@scalar/openapi-types';
+import type { PostmanCollection } from './types.js';
+/**
+ * Converts a Postman Collection to an OpenAPI 3.1.0 document.
+ * This function processes the collection's information, servers, authentication,
+ * and items to create a corresponding OpenAPI structure.
+ */
+export declare function convert(postmanCollection: PostmanCollection | string): OpenAPIV3_1.Document;
+//# sourceMappingURL=convert.d.ts.map

package/dist/convert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convert.d.ts","sourceRoot":"","sources":["../src/convert.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AASxD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAEhD;;;;GAIG;AACH,wBAAgB,OAAO,CACrB,iBAAiB,EAAE,iBAAiB,GAAG,MAAM,GAC5C,WAAW,CAAC,QAAQ,CAuKtB"}

package/dist/convert.js

@@ -0,0 +1,156 @@
+import { processAuth } from './helpers/authHelpers.js';
+import { processExternalDocs } from './helpers/externalDocsHelper.js';
+import { processItem } from './helpers/itemHelpers.js';
+import { processLicenseAndContact } from './helpers/licenseContactHelper.js';
+import { processLogo } from './helpers/logoHelper.js';
+import { parseServers } from './helpers/serverHelpers.js';
+import { normalizePath } from './helpers/urlHelpers.js';
+/**
+ * Converts a Postman Collection to an OpenAPI 3.1.0 document.
+ * This function processes the collection's information, servers, authentication,
+ * and items to create a corresponding OpenAPI structure.
+ */
+export function convert(postmanCollection) {
+    // Parse string input if provided
+    const collection = typeof postmanCollection === 'string'
+        ? JSON.parse(postmanCollection)
+        : postmanCollection;
+    // Extract title from collection info, fallback to 'API' if not provided
+    const title = collection.info.name || 'API';
+    // Look for version in collection variables, default to '1.0.0'
+    const version = collection.variable?.find((v) => v.key === 'version')?.value ||
+        '1.0.0';
+    // Handle different description formats in Postman
+    const description = typeof collection.info.description === 'string'
+        ? collection.info.description
+        : collection.info.description?.content || '';
+    // Process license and contact information
+    const { license, contact } = processLicenseAndContact(collection);
+    // Process logo information
+    const logo = processLogo(collection);
+    // Initialize the OpenAPI document with required fields
+    const openapi = {
+        openapi: '3.1.0',
+        info: {
+            title,
+            version,
+            ...(description && { description }),
+            ...(license && { license }),
+            ...(contact && { contact }),
+            ...(logo && { 'x-logo': logo }),
+        },
+        servers: parseServers(collection),
+        paths: {},
+    };
+    // Process external docs
+    const externalDocs = processExternalDocs(collection);
+    if (externalDocs) {
+        openapi.externalDocs = externalDocs;
+    }
+    // Process authentication if present in the collection
+    if (collection.auth) {
+        const { securitySchemes, security } = processAuth(collection.auth);
+        openapi.components = openapi.components || {};
+        openapi.components.securitySchemes = {
+            ...openapi.components.securitySchemes,
+            ...securitySchemes,
+        };
+        openapi.security = security;
+    }
+    // Process each item in the collection and merge into OpenAPI spec
+    if (collection.item) {
+        collection.item.forEach((item) => {
+            const { paths: itemPaths, components: itemComponents } = processItem(item);
+            // Merge paths from the current item
+            openapi.paths = openapi.paths || {};
+            for (const [pathKey, pathItem] of Object.entries(itemPaths)) {
+                // Convert colon-style params to curly brace style
+                const normalizedPathKey = normalizePath(pathKey);
+                /**
+                 * this is a bit of a hack to skip empty paths only if they have no parameters
+                 * because there is a test where if I remove the empty path it breaks the test
+                 * but there is another test where if I leave the empty path it breaks the test
+                 * so I added this check to only remove the empty path if all the methods on it have no parameters
+                 */
+                if (normalizedPathKey === '/') {
+                    const allMethodsHaveEmptyParams = Object.values(pathItem || {}).every((method) => !method.parameters || method.parameters.length === 0);
+                    if (allMethodsHaveEmptyParams) {
+                        continue;
+                    }
+                }
+                if (!openapi.paths[normalizedPathKey]) {
+                    openapi.paths[normalizedPathKey] = pathItem;
+                }
+                else {
+                    openapi.paths[normalizedPathKey] = {
+                        ...openapi.paths[normalizedPathKey],
+                        ...pathItem,
+                    };
+                }
+                // Handle the /raw endpoint specifically
+                if (normalizedPathKey === '/raw' && pathItem?.post) {
+                    if (pathItem.post.requestBody?.content['text/plain']) {
+                        pathItem.post.requestBody.content['application/json'] = {
+                            schema: {
+                                type: 'object',
+                                examples: [],
+                            },
+                        };
+                        delete pathItem.post.requestBody.content['text/plain'];
+                    }
+                }
+            }
+            // Merge security schemes from the current item
+            if (itemComponents?.securitySchemes) {
+                openapi.components = openapi.components || {};
+                openapi.components.securitySchemes = {
+                    ...openapi.components.securitySchemes,
+                    ...itemComponents.securitySchemes,
+                };
+            }
+        });
+    }
+    // Clean up the generated paths
+    if (openapi.paths) {
+        Object.values(openapi.paths).forEach((path) => {
+            if (path) {
+                Object.values(path).forEach((method) => {
+                    if (method && 'parameters' in method) {
+                        // Remove empty parameters array to keep spec clean
+                        if (method.parameters?.length === 0) {
+                            delete method.parameters;
+                        }
+                        // Handle request bodies
+                        if (method.requestBody?.content) {
+                            const content = method.requestBody.content;
+                            if (Object.keys(content).length === 0) {
+                                // Keep an empty requestBody with text/plain content
+                                method.requestBody = {
+                                    content: {
+                                        'text/plain': {},
+                                    },
+                                };
+                            }
+                            else if ('text/plain' in content) {
+                                // Preserve schema if it exists, otherwise keep an empty object
+                                if (!content['text/plain'].schema ||
+                                    Object.keys(content['text/plain'].schema).length === 0) {
+                                    content['text/plain'] = {};
+                                }
+                            }
+                        }
+                        // Ensure all methods have a description, but don't add an empty one if it doesn't exist
+                        if (!method.description) {
+                            delete method.description;
+                        }
+                    }
+                });
+            }
+        });
+    }
+    // Remove empty components object
+    if (Object.keys(openapi.components || {}).length === 0) {
+        delete openapi.components;
+    }
+    return openapi;
+}

package/dist/helpers/authHelpers.d.ts

@@ -0,0 +1,12 @@
+import type { OpenAPIV3_1 } from '@scalar/openapi-types';
+import type { Auth } from '../types.js';
+/**
+ * Processes authentication information from a Postman collection and updates
+ * the OpenAPI document with the corresponding security schemes and requirements.
+ * Supports API key, basic auth, bearer token, and OAuth2 authentication types.
+ */
+export declare function processAuth(auth: Auth): {
+    securitySchemes: Record<string, OpenAPIV3_1.SecuritySchemeObject>;
+    security: OpenAPIV3_1.SecurityRequirementObject[];
+};
+//# sourceMappingURL=authHelpers.d.ts.map

package/dist/helpers/authHelpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authHelpers.d.ts","sourceRoot":"","sources":["../../src/helpers/authHelpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAExD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,UAAU,CAAA;AAyFpC;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG;IACvC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,oBAAoB,CAAC,CAAA;IACjE,QAAQ,EAAE,WAAW,CAAC,yBAAyB,EAAE,CAAA;CAClD,CAoBA"}

package/dist/helpers/authHelpers.js

@@ -0,0 +1,99 @@
+// Constants for security scheme names and URLs
+const AUTH_SCHEMES = {
+    API_KEY: 'apikeyAuth',
+    BASIC: 'basicAuth',
+    BEARER: 'bearerAuth',
+    OAUTH2: 'oauth2Auth',
+};
+const OAUTH2_DEFAULTS = {
+    AUTHORIZE_URL: 'https://example.com/oauth/authorize',
+    TOKEN_URL: 'https://example.com/oauth/token',
+};
+/**
+ * Creates security configuration for API key authentication
+ */
+function createApiKeyConfig() {
+    return {
+        scheme: {
+            type: 'apiKey',
+            name: 'api_key',
+            in: 'header',
+        },
+        requirement: { [AUTH_SCHEMES.API_KEY]: [] },
+    };
+}
+/**
+ * Creates security configuration for Basic authentication
+ */
+function createBasicConfig() {
+    return {
+        scheme: {
+            type: 'http',
+            scheme: 'basic',
+        },
+        requirement: { [AUTH_SCHEMES.BASIC]: [] },
+    };
+}
+/**
+ * Creates security configuration for Bearer token authentication
+ */
+function createBearerConfig() {
+    return {
+        scheme: {
+            type: 'http',
+            scheme: 'bearer',
+        },
+        requirement: { [AUTH_SCHEMES.BEARER]: [] },
+    };
+}
+/**
+ * Creates security configuration for OAuth2 authentication
+ */
+function createOAuth2Config() {
+    return {
+        scheme: {
+            type: 'oauth2',
+            flows: {
+                authorizationCode: {
+                    authorizationUrl: OAUTH2_DEFAULTS.AUTHORIZE_URL,
+                    tokenUrl: OAUTH2_DEFAULTS.TOKEN_URL,
+                    scopes: {},
+                },
+            },
+        },
+        requirement: { [AUTH_SCHEMES.OAUTH2]: [] },
+    };
+}
+/**
+ * Maps authentication types to their configuration creators
+ */
+const AUTH_TYPE_HANDLERS = {
+    apikey: createApiKeyConfig,
+    basic: createBasicConfig,
+    bearer: createBearerConfig,
+    oauth2: createOAuth2Config,
+};
+/**
+ * Processes authentication information from a Postman collection and updates
+ * the OpenAPI document with the corresponding security schemes and requirements.
+ * Supports API key, basic auth, bearer token, and OAuth2 authentication types.
+ */
+export function processAuth(auth) {
+    const securitySchemes = {};
+    const security = [];
+    try {
+        const handler = AUTH_TYPE_HANDLERS[auth.type];
+        if (!handler) {
+            throw new Error(`Unsupported authentication type: ${auth.type}`);
+        }
+        const { scheme, requirement } = handler();
+        const schemeKey = `${auth.type}Auth`;
+        securitySchemes[schemeKey] = scheme;
+        security.push(requirement);
+    }
+    catch (error) {
+        console.error('Error processing authentication:', error);
+        throw error;
+    }
+    return { securitySchemes, security };
+}

package/dist/helpers/externalDocsHelper.d.ts

@@ -0,0 +1,10 @@
+import type { OpenAPIV3_1 } from '@scalar/openapi-types';
+import type { PostmanCollection } from '../types.js';
+/**
+ * Processes the external documentation information from a Postman Collection.
+ * This function checks for 'externalDocs.url' and 'externalDocs.description'
+ * in the collection variables and creates an OpenAPI External Documentation Object
+ * if the URL is present.
+ */
+export declare function processExternalDocs(collection: PostmanCollection): OpenAPIV3_1.ExternalDocumentationObject | undefined;
+//# sourceMappingURL=externalDocsHelper.d.ts.map

package/dist/helpers/externalDocsHelper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"externalDocsHelper.d.ts","sourceRoot":"","sources":["../../src/helpers/externalDocsHelper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAExD,OAAO,KAAK,EAAE,iBAAiB,EAAY,MAAM,UAAU,CAAA;AAkB3D;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,iBAAiB,GAC5B,WAAW,CAAC,2BAA2B,GAAG,SAAS,CA2BrD"}

package/dist/helpers/externalDocsHelper.js

@@ -0,0 +1,40 @@
+// Constants for variable keys
+const VARIABLE_KEYS = {
+    URL: 'externalDocs.url',
+    DESCRIPTION: 'externalDocs.description',
+};
+/**
+ * Finds a specific variable in the collection by its key
+ */
+function findVariable(collection, key) {
+    return collection.variable?.find((v) => v.key === key);
+}
+/**
+ * Processes the external documentation information from a Postman Collection.
+ * This function checks for 'externalDocs.url' and 'externalDocs.description'
+ * in the collection variables and creates an OpenAPI External Documentation Object
+ * if the URL is present.
+ */
+export function processExternalDocs(collection) {
+    try {
+        const urlVariable = findVariable(collection, VARIABLE_KEYS.URL);
+        const descriptionVariable = findVariable(collection, VARIABLE_KEYS.DESCRIPTION);
+        if (!urlVariable?.value) {
+            return undefined;
+        }
+        if (typeof urlVariable.value !== 'string') {
+            throw new Error('External docs URL must be a string');
+        }
+        return {
+            url: urlVariable.value,
+            ...(descriptionVariable?.value &&
+                typeof descriptionVariable.value === 'string' && {
+                description: descriptionVariable.value,
+            }),
+        };
+    }
+    catch (error) {
+        console.error('Error processing external docs:', error);
+        throw error;
+    }
+}

package/dist/helpers/formDataHelpers.d.ts

@@ -0,0 +1,8 @@
+import type { OpenAPIV3_1 } from '@scalar/openapi-types';
+import type { FormParameter } from '../types.js';
+/**
+ * Processes form data parameters from a Postman request and converts them into an OpenAPI schema.
+ * Handles file uploads, required fields, and descriptions.
+ */
+export declare function processFormDataSchema(formdata: FormParameter[]): OpenAPIV3_1.SchemaObject;
+//# sourceMappingURL=formDataHelpers.d.ts.map

package/dist/helpers/formDataHelpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formDataHelpers.d.ts","sourceRoot":"","sources":["../../src/helpers/formDataHelpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAExD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAE7C;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,aAAa,EAAE,GACxB,WAAW,CAAC,YAAY,CA6C1B"}

package/dist/helpers/formDataHelpers.js

@@ -0,0 +1,42 @@
+/**
+ * Processes form data parameters from a Postman request and converts them into an OpenAPI schema.
+ * Handles file uploads, required fields, and descriptions.
+ */
+export function processFormDataSchema(formdata) {
+    const schema = {
+        type: 'object',
+        properties: {},
+        required: [],
+    };
+    formdata.forEach((item) => {
+        if (!schema.properties)
+            return;
+        const property = {
+            type: 'string',
+        };
+        // Add description if present, handling both string and object descriptions
+        if (item.description) {
+            const descriptionText = typeof item.description === 'string'
+                ? item.description
+                : item.description.content || '';
+            property.description = descriptionText.replace(' [required]', '');
+            // If [required] was present, add to required array
+            if (descriptionText.includes('[required]')) {
+                schema.required?.push(item.key);
+            }
+        }
+        // Handle file type fields
+        if (item.type === 'file') {
+            property.format = 'binary';
+        }
+        else {
+            property.example = item.value;
+        }
+        schema.properties[item.key] = property;
+    });
+    // Only keep required array if it has items
+    if (schema.required?.length === 0) {
+        delete schema.required;
+    }
+    return schema;
+}

package/dist/helpers/itemHelpers.d.ts

@@ -0,0 +1,13 @@
+import type { OpenAPIV3_1 } from '@scalar/openapi-types';
+import type { Item, ItemGroup } from '../types.js';
+/**
+ * Processes a Postman collection item or item group and returns
+ * the corresponding OpenAPI paths and components.
+ * Handles nested item groups, extracts request details, and generates corresponding
+ * OpenAPI path items and operations.
+ */
+export declare function processItem(item: Item | ItemGroup, parentTags?: string[], parentPath?: string): {
+    paths: OpenAPIV3_1.PathsObject;
+    components: OpenAPIV3_1.ComponentsObject;
+};
+//# sourceMappingURL=itemHelpers.d.ts.map

package/dist/helpers/itemHelpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"itemHelpers.d.ts","sourceRoot":"","sources":["../../src/helpers/itemHelpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAExD,OAAO,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAuB/C;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,IAAI,GAAG,SAAS,EACtB,UAAU,GAAE,MAAM,EAAO,EACzB,UAAU,GAAE,MAAW,GACtB;IACD,KAAK,EAAE,WAAW,CAAC,WAAW,CAAA;IAC9B,UAAU,EAAE,WAAW,CAAC,gBAAgB,CAAA;CACzC,CA6LA"}