Open-Source Testing · apideck-libraries

portman

Portman is a CLI tool that converts OpenAPI specifications into Postman collections and automatically injects contract, variation, and fuzz tests. It integrates with Newman for automated testing and supports uploading collections to Postman workspaces, making it suitable for API-first CI/CD pipelines.

Talk to DEV.co Discuss Implementation

Source: GitHub — github.com/apideck-libraries/portman

685

GitHub stars

Forks

TypeScript

Primary language

Apache-2.0

License (OSI-approved)

Key facts

Objective fields from the source. Values we can't verify are shown as “Unknown” rather than guessed.

Field	Value
Repository	apideck-libraries/portman
Owner	apideck-libraries
Primary language	TypeScript
License	Apache-2.0 — OSI-approved
Stars	685
Forks	61
Open issues	50
Latest release	v1.35.0 (2026-05-23)
Last updated	2026-05-23
Source	https://github.com/apideck-libraries/portman

What portman is

Written in TypeScript, Portman leverages openapi-to-postman and openapi-format libraries to transform OAS 3.0/3.1 documents into executable Postman collections. It provides configuration-driven test injection, request parameter resolution, collection variable assignment, and Newman test execution within a single CLI workflow.

Quickstart

Get the portman source

Clone the repository and explore it locally.

terminalbash

1git clone https://github.com/apideck-libraries/portman.git2cd portman3# follow the project's README for install & configuration

Need it deployed, integrated, or customized instead? DEV.co ships production installs.

Best use cases

Contract-First API Testing in CI/CD

Automatically generate Postman collections with contract tests from OpenAPI specs, enabling rapid validation of API conformance to specification in automated pipelines without manual test creation.

API Documentation to Live Test Suite

Convert existing OpenAPI documentation directly into executable test collections, reducing the gap between spec and validation and ensuring documentation accuracy through continuous contract testing.

Multi-Environment API Validation

Use configuration files to define environment-specific variables and test variations, allowing the same OpenAPI spec to generate tailored Postman collections for dev, staging, and production environments.

Implementation considerations

Requires Node.js runtime and npm/yarn for installation; CLI invocation via npx, local, or global install depending on deployment context.
Configuration driven via multiple JSON/YAML files (portman-config.json, postman-config.json, oas-format-filter.json); file organization and validation critical for scaling across teams.
OpenAPI spec quality directly impacts collection usefulness; incomplete schema definitions, missing examples, or unresolved $refs will result in incomplete or invalid Postman requests.
Newman integration requires separate setup of environment variables, iteration data, and test assertions; Portman generates the collection but does not enforce test logic.
Postman API authentication (API key/token) mandatory for syncPostman and collection upload features; secure credential storage required in CI/CD environments.

When to avoid it — and what to weigh

Graphql-First Architecture — Portman is built explicitly for OpenAPI/Swagger specs. If your APIs are primarily GraphQL, this tool is not applicable.
Non-JSON/YAML Spec Formats — Only OpenAPI 3.0 and 3.1 are supported. If your API contracts use Protocol Buffers, WSDL, or other formats, conversion would require pre-processing.
Minimal Test Requirements — If you only need basic smoke tests and do not require contract validation, variation testing, or fuzzing, the overhead of configuration and test generation may not justify adoption.
Postman Alternative Ecosystems — If your organization has standardized on API testing frameworks other than Postman (e.g., REST Assured, Karate, SoapUI), integrating Portman's output may conflict with existing tooling and practices.

License & commercial use

Licensed under Apache License 2.0 (SPDX: Apache-2.0). A permissive OSI-approved license permitting commercial use, modification, and distribution with warranty disclaimers and liability limitations. Requires retention of license and copyright notices.

Apache-2.0 is a permissive license that explicitly permits commercial use, including proprietary derivative works. No additional licensing or permission is required for commercial deployment. However, verify compliance with any third-party dependencies (e.g., openapi-to-postman, openapi-format) independently.

DEV.co evaluation signals

Editorial assessment — not user reviews. Directional, with an explicit confidence level.

Signal	Assessment
Maintenance	Active
Documentation	Adequate
License clarity	Clear
Deployment complexity	Low
DEV.co fit	Strong
Assessment confidence	High

Security considerations

Requires secure handling of Postman API keys when using syncPostman functionality; recommend environment variable injection in CI/CD rather than plaintext config. CLI accepts .env files for variable injection into collections; ensure .env files are not committed to version control and are restricted to sensitive environments. No explicit security audit or vulnerability disclosure policy documented in provided DATA. Review dependency chain (openapi-to-postman, openapi-format, Newman) for known CVEs before production deployment.

Alternatives to consider

Insomnia

Native OpenAPI import and test generation with built-in environment management; lacks CLI-first, CI/CD-optimized workflow that Portman emphasizes. Proprietary SaaS with alternative commercial model.

Swagger UI / SwaggerHub

Strong for OpenAPI visualization and documentation; limited for automated test suite generation and CI/CD integration. Requires separate test framework (e.g., Karate, REST Assured) for contract testing.

Prism (Stoplight)

OpenAPI-to-mock-server tool for contract testing; does not generate Postman collections or Newman-compatible test suites. Complementary rather than direct alternative.

Software development agency

Build on portman with DEV.co software developers

Use Portman to convert your OpenAPI documentation into executable test suites and integrate contract testing into your CI/CD pipeline. Start with a local install or try npx @apideck/portman today.

Talk to DEV.co

Related open-source tools

Surfaced by semantic similarity across the DEV.co open-source index.

milkman resterm mimesis

Related on DEV.co

Explore the category and the services that help you build with it.

Open-Source Testing API Development AI Development DevOps Talk to DEV.co

portman FAQ

Can Portman convert GraphQL schemas to Postman collections?

No. Portman is designed exclusively for OpenAPI 3.0 and 3.1 specifications. GraphQL schemas require separate tooling (e.g., GraphQL Code Generator, Altair GraphQL Client).

Is Postman account required to use Portman?

No. Portman generates standard Postman collection JSON files locally without requiring a Postman account. However, Postman account and API key are required only if using the syncPostman flag to upload collections to Postman workspaces.

Can Portman run tests without Newman?

Portman generates Postman collections with embedded test scripts (contract, variation, fuzz tests). These tests execute via Newman (Postman's CLI runner) or within Postman UI. Portman does not provide an alternative test execution engine.

How does Portman handle OpenAPI specs with circular references?

By default, Portman may fail on circular references. Use the --ignoreCircularRefs flag to skip circular reference resolution, though this may result in incomplete request definitions. Pre-process specs or use openapi-format filtering to resolve complex circular dependencies.

Software developers & web developers for hire

Adopting portman is usually one piece of a larger software development effort. As a software development agency, DEV.co provides software development services and web development expertise — pairing senior software developers and web developers with your team to design, build, and operate open-source testing software in production.

Automate Your API Testing from OpenAPI Specs

Use Portman to convert your OpenAPI documentation into executable test suites and integrate contract testing into your CI/CD pipeline. Start with a local install or try npx @apideck/portman today.

Talk to DEV.co Schedule a Consultation