api-collection-converter

Convert API collections between formats — Postman, Swagger, OpenAPI, Insomnia, HAR, cURL, RAML, GraphQL, WSDL, and AWS API Gateway.

All conversions route through ATA (the hub format): Source -> ATA -> Target.

Install

npm install api-collection-converter

Quick Start

import { postman, swagger, openapi, curl, har, insomnia, ata, graphql } from 'api-collection-converter';

// Postman -> ATA
const result = postman.toAta(postmanJson);

// ATA -> Postman
const out = ata.toPostman(ataCollection);

// Postman -> Swagger (via ATA hub)
const spec = postman.toSwagger(postmanJson);

// Swagger -> cURL commands
const cmds = swagger.toCurl(swaggerJson);

// OpenAPI 3.x -> Postman
const pm = openapi.toPostman(openapiSpec);

// cURL -> ATA
const parsed = curl.toAta("curl -X GET 'https://api.example.com/users'");

// HAR -> Swagger
const sw = har.toSwagger(harLog);

// Insomnia -> Postman
const collection = insomnia.toPostman(insomniaExport);

Supported Formats

| Format | Import (toAta) | Export (fromAta) | |--------|:-:|:-:| | Postman v2.1.0 | Yes | Yes | | Swagger 2.0 | Yes | Yes | | OpenAPI 3.x | Yes | Yes | | cURL | Yes | Yes | | HAR 1.2 | Yes | Yes | | Insomnia v4 | Yes | Yes | | GraphQL Introspection | Yes | - | | RAML | Yes* | - | | WSDL/SOAP | Yes* | - | | AWS API Gateway | Yes | - |

* Requires optional peer dependency (js-yaml for RAML, fast-xml-parser for WSDL).

API

Every facade exposes toAta() plus to<Format>() methods for cross-format conversion. All functions are synchronous and return a ConvertResult:

interface ConvertResult<T> {
  success: boolean;
  data?: T;
  warnings?: string[];
  error?: string;
}

Facades

postman.toAta(json)          postman.toSwagger(json)       postman.toOpenApi(json)
postman.toCurl(json)         postman.toHar(json)           postman.toInsomnia(json)

swagger.toAta(json)          swagger.toPostman(json)       swagger.toOpenApi(json)
swagger.toCurl(json)         swagger.toHar(json)           swagger.toInsomnia(json)

openapi.toAta(json)          openapi.toPostman(json)       openapi.toSwagger(json)
openapi.toCurl(json)         openapi.toHar(json)           openapi.toInsomnia(json)

curl.toAta(str)              curl.toPostman(str)           curl.toSwagger(str)
curl.toOpenApi(str)

har.toAta(json)              har.toPostman(json)           har.toSwagger(json)
har.toCurl(json)

insomnia.toAta(json)         insomnia.toPostman(json)      insomnia.toSwagger(json)
insomnia.toCurl(json)

graphql.toAta(introspection) graphql.toPostman(introspection) graphql.toSwagger(introspection)

raml.toAta(yamlStr)          raml.toPostman(yamlStr)       raml.toSwagger(yamlStr)

wsdl.toAta(xmlStr)           wsdl.toPostman(xmlStr)        wsdl.toSwagger(xmlStr)

awsGateway.toAta({ apiDetails, resources, baseUrl })
awsGateway.toPostman(...)    awsGateway.toSwagger(...)

ata.toPostman(collection)    ata.toSwagger(collection)     ata.toOpenApi(collection)
ata.toCurl(collection)       ata.toHar(collection)         ata.toInsomnia(collection)

Generic convert() Function

import { convert } from 'api-collection-converter';

const result = convert('postman', 'swagger', postmanJson);

Custom Logger

import { postman } from 'api-collection-converter';

const result = postman.toAta(json, {
  logger: {
    debug: console.debug,
    info: console.info,
    warn: console.warn,
    error: console.error,
  }
});

Optional Dependencies

For RAML and WSDL support, install the optional peer dependencies:

# For RAML parsing
npm install js-yaml

# For WSDL/XML parsing
npm install fast-xml-parser

These are not required for other formats.

Exported Utilities

import {
  removeCommentsFromJSON,   // Strip comments from JSON-like strings
  prepareExportJson,        // Remove internal DB fields from export objects
  dereferenceLocalRefs,     // Resolve $ref pointers in OpenAPI/Swagger specs
  buildExampleFromSchema,   // Generate example values from JSON Schema
  generateId,               // UUID generator with fallback
  ITEM_CATEGORY,            // ATA category constants
  VAR_TYPE,                 // ATA variable type constants
  REQ_METHOD,               // HTTP method constants
} from 'api-collection-converter';

Exported Types

import type {
  AtaCollection, AtaRequest, AtaFolder,
  PostmanCollection, SwaggerSpec, OpenApiSpec,
  HarLog, CurlCommand, InsomniaExport,
  GraphQLIntrospection, WsdlDefinition,
  ConvertResult, ConvertOptions, FormatName, Logger,
} from 'api-collection-converter';

Build

npm run build      # ESM + CJS + .d.ts
npm test           # Run all tests
npm run typecheck  # TypeScript check

License

MIT