Postman Alchemy

Automatic Postman collection generator and test automation from OpenAPI specs and GraphQL schemas.

Features

• 🚀 Generate Postman collections from OpenAPI specifications
• 🔥 Generate Postman collections from GraphQL schemas
• 🧪 Automatic test generation with realistic data
• 📤 Direct upload to Postman workspace
• 🌍 Environment variable support
• 📁 Organized folder structure

Installation

npm install -g postman-alchemy

Usage

OpenAPI Support

Generate a Postman collection from an OpenAPI specification:

postman-alchemy \
  --key YOUR_POSTMAN_API_KEY \
  --workspace YOUR_WORKSPACE_ID \
  --collection "My API Collection" \
  --folder "API Endpoints" \
  --type openapi \
  --spec ./openapi.json \
  --group "v1"

GraphQL Support

Generate a Postman collection from a GraphQL schema:

postman-alchemy \
  --key YOUR_POSTMAN_API_KEY \
  --workspace YOUR_WORKSPACE_ID \
  --collection "My GraphQL API" \
  --folder "GraphQL Endpoints" \
  --type graphql \
  --graphql ./schema.json \
  --group "graphql"

With Environment Variables

postman-alchemy \
  --key YOUR_POSTMAN_API_KEY \
  --workspace YOUR_WORKSPACE_ID \
  --collection "My API Collection" \
  --folder "API Endpoints" \
  --type graphql \
  --graphql ./schema.json \
  --env "Development" \
  --vars '{"baseUrl":"https://api.example.com","apiKey":"your-api-key"}'

CLI Options

| Option | Short | Description | Required | |--------|-------|-------------|----------| | --key | -k | Postman API Key | ✅ | | --workspace | -w | Postman Workspace ID | ✅ | | --collection | -c | Collection Name | ✅ | | --folder | -f | Folder Name | ✅ | | --type | -t | API type: openapi or graphql | ✅ | | --spec | -s | Path to OpenAPI spec file | ✅ (for openapi) | | --graphql | -g | Path to GraphQL schema file | ✅ (for graphql) | | --group | -gr | Group name for API endpoints | ❌ | | --env | -e | Environment name | ❌ | | --vars | -v | Environment variables (JSON string) | ❌ |

GraphQL Schema Format

The GraphQL schema file should be in introspection query result format. You can generate this from your GraphQL endpoint:

# Using GraphQL CLI
graphql get-schema --endpoint http://localhost:4000/graphql --output schema.json

# Using curl
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"query":"query IntrospectionQuery { __schema { queryType { name } mutationType { name } subscriptionType { name } types { ...FullType } } } fragment FullType on __Type { kind name description fields(includeDeprecated: true) { name description args { ...InputValue } type { ...TypeRef } isDeprecated deprecationReason } inputFields { ...InputValue } interfaces { ...TypeRef } enumValues(includeDeprecated: true) { name description isDeprecated deprecationReason } possibleTypes { ...TypeRef } } fragment InputValue on __InputValue { name description type { ...TypeRef } defaultValue } fragment TypeRef on __Type { kind name ofType { kind name ofType { kind name ofType { kind name ofType { kind name ofType { kind name ofType { kind name ofType { kind name } } } } } } } }"}' \
  http://localhost:4000/graphql > schema.json

Programmatic Usage

OpenAPI

import PostmanAlchemy from 'postman-alchemy';

const alchemy = new PostmanAlchemy({
  postmanApiKey: 'your-api-key',
  workspaceId: 'your-workspace-id',
  collectionName: 'My API Collection',
  folderName: 'API Endpoints',
  type: 'openapi',
  openApiPath: './openapi.json',
  groupName: 'v1',
  environment: {
    name: 'Development',
    variables: {
      baseUrl: 'https://api.example.com',
      apiKey: 'your-api-key'
    }
  }
});

await alchemy.generateAndUpload();

GraphQL

import PostmanAlchemy from 'postman-alchemy';

const alchemy = new PostmanAlchemy({
  postmanApiKey: 'your-api-key',
  workspaceId: 'your-workspace-id',
  collectionName: 'My GraphQL API',
  folderName: 'GraphQL Endpoints',
  type: 'graphql',
  graphqlSchemaPath: './schema.json',
  groupName: 'graphql',
  environment: {
    name: 'Development',
    variables: {
      baseUrl: 'https://api.example.com',
      graphqlEndpoint: 'https://api.example.com/graphql'
    }
  }
});

await alchemy.generateAndUpload();

Generated GraphQL Collections

When using GraphQL mode, the tool will:

1. Parse the GraphQL schema from the introspection result
2. Generate queries for each field in the Query type
3. Generate mutations for each field in the Mutation type
4. Create organized folders separating queries and mutations
5. Add realistic variables with example values for each argument
6. Include comprehensive tests for GraphQL-specific validations

Example Generated Query

query getUser($id: ID!) {
  user(id: $id) {
    id
    name
    email
    createdAt
  }
}

With variables:

{
  "id": "example_string"
}

Example Generated Mutation

mutation createUser($input: CreateUserInput!) {
  createUser(input: $input) {
    id
    name
    email
    createdAt
  }
}

With variables:

{
  "input": {
    "name": "example_string",
    "email": "example_string"
  }
}

Getting Your Postman API Key

1. Go to Postman API Keys
2. Click "Generate API Key"
3. Give it a name and click "Generate API Key"
4. Copy the generated key

Getting Your Workspace ID

1. Go to your Postman workspace
2. Look at the URL: https://app.postman.com/workspace/{workspace-id}
3. Copy the workspace ID from the URL

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.