repository·main·Indexed 20 days ago
https://github.com/apideck-libraries/portmanA CLI tool that converts OpenAPI 3.0 and 3.1 specifications into Postman collections. It automates the generation of contract, variation, and integration tests for CI/CD pipelines. Key features include OpenAPI document filtering, Newman test execution, global collection customizations (scripts, variables, and security overwrites), and mass replacement utilities.
Portman supports template expressions to dynamically construct Postman variable names based on OpenAPI operation metadata. These expressions are wrapped in < and > and allow you to create unique variable names for different operations (e.g., using tags or operation IDs) within a single configuration directive.
Supported template expressions include:
<operationId>: The operationId of the OpenAPI operation (e.g., leadsAll).<method>: The HTTP method (e.g., GET).<path>: The full path (e.g., /crm/leads).<pathRef>: The Portman path reference (e.g., GET::/crm/leads).<opsRef>: The operationId with a fallback to pathRef if operationId is missing.<tag>: The first tag name (e.g., Leads).<tag1>, <tag2>, <tagn>: The nth tag name.<pathPart1>, <pathPart2>, <pathPartn>: The nth part of the path (e.g., crm, leads).# Example OpenAPI operation
path:
/crm/leads:
get:
tags:
- Leads
- CRM
operationId: leadsAllA Portman configuration file is a JSON object that defines how an OpenAPI specification is transformed into a Postman collection. The top-level structure includes:
version: The JSON Portman configuration version.tests: Definitions for generated contract, variation, integration, and content tests.contractTests: Options for autogenerated contract tests.contentTests: Additional Postman tests to check response content.variationTests: Options for defining variation tests.integrationTests: Options for defining integration tests.extendTests: Custom additions of manually created Postman tests.assignVariables: Settings for Postman collection variables to facilitate automation.overwrites: Custom modifications of OpenAPI/Postman request data.operationPreRequestScripts: Injected Postman Pre-request Scripts.globals: Customizations applied to the entire Postman collection.To apply tests, variables, or overwrites to specific endpoints, use targeting options. Portman supports three ways to identify an operation:
openApiOperationId (String): The exact operationId from the OpenAPI spec (e.g., "leadsAll").openApiOperationIds (Array): A list of operationId strings.openApiOperation (String): A combination of the HTTP method and path using a :: separator (e.g., "GET::/crm/leads").Wildcard Matching for openApiOperation:
"*::/crm/leads" targets all methods for that path."GET::/crm/*" targets the GET method for any path under /crm/."*::/crm/*" targets all methods and all paths under /crm/.Exclusions:
Use excludeForOperations (Array) to skip specific operations. This is particularly useful when using wildcards to exclude certain endpoints from a broad match. Example: ["leadsAdd", "GET::/crm/leads/{id}"].
{
"openApiOperation": "*::/crm/*",
"excludeForOperations": ["leadsAdd"]
}Fuzzing (or fuzz testing) in Portman is an automated technique to trigger validation and error responses in your API by providing unexpected or invalid data. Portman generates new Postman requests based on OpenAPI request properties, where each variation is designed to test contract constraints.
Key Behaviors:
application/json media types.Available Fuzzing Variations:
For requestBody, requestQueryParams, and requestHeaders, you can enable:
requiredFields (Boolean): Removes properties marked as required in OpenAPI.minimumNumberFields (Boolean): Changes numeric values to be lower than the defined minimum.maximumNumberFields (Boolean): Changes numeric values to be higher than the defined maximum.minLengthFields (Boolean): Changes string lengths to be lower than the defined minLength.maxLengthFields (Boolean): Changes string lengths to be higher than the defined maxLength.When defining contentTests in your Portman settings, you can target specific operations using two different methods:
operationId: Target a specific operation using its unique ID defined in your OpenAPI specification (e.g., leadsOne).openApiOperation: Target an operation by combining its HTTP method and path using the format METHOD::/path (e.g., GET::/crm/leads)."contentTests": [
{
"openApiOperation": "GET::/crm/leads",
"responseBodyTests": [
{
"key": "data[0].company_name",
"value": "Spacex"
}
]
}
]Portman allows you to automatically assign values from API responses (body or headers) or request bodies to Postman collection variables. This is useful for creating automated flows where a value from one request (like a newly created entity's ID) is needed for subsequent requests (like Read, Update, or Delete operations).
Variables are mapped to Postman requests based on the OpenAPI operationId or a combination of the HTTP method and path.
"assignVariables": [
{
"openApiOperationId": "leadsAdd",
"collectionVariables": [
{
"responseBodyProp": "data.id",
"name": "leadsAdd.id"
}
]
}
]Portman supports using JSON/YAML references ($ref) within your configuration files. This allows you to reuse configuration segments across multiple setups or split large configurations into smaller, more manageable files.
References can point to either:
A $ref string must include both the file path and the specific definition path (using the # fragment syntax).
version: 1
tests:
contractTests:
$ref: './examples/config-references/definitions/test-contracts.yaml#/contractTests'
contentTests:
$ref: './examples/config-references/definitions/test-content.yaml#/contentTests'
globals:
$ref: 'https://raw.githubusercontent.com/apideck-libraries/portman/main/examples/config-references/definitions/globals.yaml#/globals'The globals section in a Portman configuration file allows you to apply customizations to the entire generated Postman collection. This includes injecting scripts, setting variables, performing mass replacements, and overwriting security schemas. The configuration follows this structure:
{
"version": 1.0,
"globals": { ... }
}{
"version": 1.0,
"globals": {
"stripResponseExamples": true,
"collectionPreRequestScripts": [
"pm.collectionVariables.set('status', pm.iterationData.get('status') || 'open')"
],
"collectionTestScripts": [
"pm.collectionVariables.set('applicationId', pm.iterationData.get('applicationId') || '1111');"
],
"collectionVariables": {
"name": "portman",
"version": "1"
},
"keyValueReplacements": {
"x-apideck-app-id": "{{applicationId}}"
},
"valueReplacements": {
"<Bearer Token>": "{{bearerToken}}"
},
"rawReplacements": [
{
"searchFor": "Unify",
"replaceWith": "Unify ApiDeck"
}
],
"portmanReplacements": [
{
"searchFor": "]::",
"replaceWith": "]-:"
}
]
}
}Portman allows you to manipulate the generated Postman collection to facilitate automation. You can overwrite or modify request bodies, headers, query parameters, and path variables. This is useful for:
Overwrites are mapped to specific OpenAPI operations using either openApiOperationId or openApiOperation.
portman --cliOptionsFile ./examples/testsuite-overwrites/portman-cli-options.jsonThe variationTests property in your Portman JSON configuration allows you to inject specific test variations into the generated Postman collection.
You can target specific operations for variations using:
openApiOperationId (String): The OpenAPI operationId (e.g., leadsAll).openApiOperation (String): A combination of method and path (e.g., GET::/crm/leads).excludeForOperations (Array): Operations to skip.Each variation within the variations array can include:
name: The name used in the Postman collection.openApiResponse (Optional): The expected response code or code::content-type (e.g., 404 or 200::text/*). If omitted, it defaults to the first response in the OpenAPI spec.openApiRequest (Optional): The request content-type (e.g., application/*).overwrites: Custom modifications to the request data.tests: A collection of contractTests, contentTests, and extendTests specific to this variation.assignVariables: Postman collection variables assigned based on the variation's response.While Portman's default contract tests validate the structure and properties of requests and responses, Content Tests allow you to validate the actual values returned by an API.
Content tests are used to ensure that specific properties in the response body or headers match expected values, follow certain constraints (like length), or exist within a set of allowed values. This is useful for converting OpenAPI definitions into Postman collections that include functional validation of data, not just schema validation.