Skip to content

Release Notes: v0.3.0

Release Date: 2026-03-21

Overview

Traffic2OpenAPI v0.3.0 introduces Postman Collection v2.1 support, enabling OpenAPI spec generation from existing Postman collections. This release also extends the IR schema with documentation fields for preserving API metadata throughout the conversion pipeline.

Highlights

  • Postman Collection Converter: Convert Postman Collection v2.1 files to IR format for OpenAPI generation
  • IR Documentation Fields: Extended schema with Documentation, APIMetadata, and Tags fields
  • Enhanced Inference Engine: Documentation support for operation summaries and descriptions

New Features

Postman Collection Converter

The new pkg/postman package converts Postman Collection v2.1 files to IR format:

import "github.com/grokify/traffic2openapi/pkg/postman"

// Convert Postman collection to IR records
records, metadata, err := postman.ConvertFile(ctx, "collection.json", nil)
if err != nil {
    log.Fatal(err)
}

// Create batch with metadata
batch := ir.NewBatchWithMetadata(records, metadata)

Features include:

  • Request Elements: Method, URL, headers, query params, path params, body (raw, form-data, urlencoded)
  • Path Parameters: Automatic conversion from Postman :id format to OpenAPI {id} format
  • Authentication: Extract bearer tokens, basic auth, and API key settings
  • Documentation: Preserve collection name, description, version, and item descriptions

CLI Support

Convert Postman collections via the CLI:

# Basic conversion
traffic2openapi convert postman -i collection.json -o traffic.ndjson

# With variable substitution
traffic2openapi convert postman -i collection.json -o traffic.ndjson \
    --var baseUrl=https://api.example.com \
    --var apiKey=sk-xxx

# Filter by host or method
traffic2openapi convert postman -i collection.json -o traffic.ndjson \
    --host api.example.com --method POST

# Skip authentication headers
traffic2openapi convert postman -i collection.json -o traffic.ndjson --auth=false

New flags for convert postman:

Flag Description
--base-url Override base URL for all requests
--var Variable substitution (key=value, repeatable)
--host Filter by host
--method Filter by HTTP method
--auth Include auth headers (default: true)
--filter-headers Header patterns to exclude (comma-separated)

IR Schema Extensions

The IR schema now includes documentation fields:

type IRRecord struct {
    // ... existing fields ...
    Documentation *Documentation `json:"documentation,omitempty"`
    Tags          []string       `json:"tags,omitempty"`
}

type Documentation struct {
    Summary     string `json:"summary,omitempty"`
    Description string `json:"description,omitempty"`
}

type APIMetadata struct {
    Name        string `json:"name,omitempty"`
    Description string `json:"description,omitempty"`
    Version     string `json:"version,omitempty"`
}

These fields flow through the pipeline:

  1. Postman Converter: Extracts metadata from collection info and item names/descriptions
  2. Inference Engine: Preserves and aggregates documentation across requests
  3. OpenAPI Generator: Maps to OpenAPI summary, description, and info fields

Workflow Example

Convert a Postman collection to OpenAPI:

# 1. Convert Postman collection to IR
traffic2openapi convert postman -i my-api.postman_collection.json -o traffic.ndjson

# 2. Generate OpenAPI spec
traffic2openapi generate -i traffic.ndjson -o openapi.yaml \
    --title "My API" \
    --server https://api.example.com

# 3. Validate the spec
traffic2openapi validate-spec openapi.yaml

Supported Postman Features

Feature Supported Notes
Collection v2.1 Yes Standard Postman format
Request method Yes GET, POST, PUT, PATCH, DELETE, etc.
URL with path/query Yes Full URL parsing
Headers Yes All headers preserved
Path parameters Yes :id → {id} conversion
Body (raw JSON/XML) Yes Content-Type detection
Body (form-data) Yes Multipart forms
Body (urlencoded) Yes Form submissions
Bearer auth Yes Token extraction
Basic auth Yes Username/password
API key auth Yes Header or query param
OAuth2 Partial Flow configuration
Folders Yes Hierarchy preserved
Variables No Use --var flag to substitute

Dependencies

  • Added github.com/rbretecher/go-postman-collection v0.9.0
  • Updated github.com/pb33f/libopenapi from v0.34.2 to v0.34.3

Upgrade Guide

This release is backwards compatible with v0.2.0. New features are additive.

The IR schema changes are backwards compatible - existing IR files without documentation fields will continue to work.

What's Next

Planned for future releases:

  • Additional adapters (mitmproxy, Insomnia, Bruno)
  • Postman environment variable resolution
  • Response example extraction from Postman collections
  • OpenAPI to Postman collection export