The following are frequently asked questions about Postman’s Spec Hub feature. Use these questions to learn about different behavior when generating and syncing between collections and specifications in Spec Hub.
This section includes behavior when generating an API specification from a collection, or syncing changes from a collection to a specification. Learn more about generating a specification from a collection and keeping them in sync.
The parameters are consolidated into path-level parameters. If any updates, like changes to descriptions or data type schemas, are made to the shared parameters in the collection, users must ensure these updates are applied consistently across all methods under that path.
If inconsistencies are detected in the path parameters across methods, the system defaults to using the last defined instance of the path parameter within that path.
Only applies when you generate a specification from a collection.
Query parameters from the first request in the collection are prioritized and added as operation-level parameters in the specification.
Examples or example values explicitly defined in the specification remain unchanged and preserved, even when related schemas or components are updated. By default, the system doesn’t generate or sync values from collections to specifications.
To sync values from a collection to specification, you can enable this option in sync settings.
OpenAPI 2.0 responses support only a single examples object. When generating a collection from a specification, Postman uses the first example available. During synchronization, any updates to the response body in the collection are applied to the first example in the specification.
Only applies when you sync changes from a collection to a specification.
The request is preserved in the specification to prevent accidental or unintentional data loss.
Only applies when you generate a specification from a collection.
Only user-defined headers are included in the specification. This helps ensure that the generated specifications are clear and accurate.
The system only generates and synchronizes request bodies in JSON format (application/json content type). If a path in the collection has a request body in a format other than JSON (such as text/plain or application/xml content types), the request body isn’t included in the specification. All non-JSON request bodies are preserved in the collection.
Postman doesn’t support non-JSON body types, like form-data or multipart. These request bodies are excluded from the specification.
When you generate a collection from a specification with reusable components, the entire reference object is copied to requests in the generated collection. If you make changes to the requests and then sync the changes back to the specification, references are converted into inline components in the specification. This ensures that any detected updates are accurately reflected in the output.
Only applies when you sync changes from a collection to a specification.
Changes in a collection may overwrite the changes in a specification. All changes to the specification are lost in this scenario. It’s recommended that you don’t apply changes to the specification and collection at the same time to prevent data loss.
The following exceptions apply:
Only applies when you sync changes from a collection to a specification.
All x- vendor extensions are preserved in the specification. Vendor extensions aren’t removed or modified, ensuring that any organization-specific metadata remains complete.
OpenAPI 2.0 only supports a single host value. When generating or syncing a specification from a collection, Postman uses the first host encountered in the collection’s requests and applies it to the specification.
consumes and produces handled in OpenAPI 2.0?When syncing to an OpenAPI 2.0 specification, Postman adds the consumes (request content type) and produces (response content type) fields at the operation (method) level for each endpoint.
basePath generated when creating an OpenAPI 2.0 specification from a collection?No, Postman doesn’t generate the basePath when creating an OpenAPI 2.0 specification from a collection. However, if a basePath already exists in the specification, it’s retained during synchronization.
webhooks in OpenAPI 3.1?In OpenAPI 3.1, Postman automatically generates webhooks object from collection requests inside a Webhooks folder. These webhooks are included by default, and synchronized during a two-way sync.
Postman uses the default JSON schema 2020-12 dialect when generating an OpenAPI 3.1 specification from a collection.
This section includes behavior when generating a collection from an API specification, or syncing changes from a specification to a collection. Learn more about generating a collection from a specification and keeping them in sync.
The parameter in the collection inherits the description from the common path-level parameter in the specification.
Only applies when you sync changes from a specification to a collection.
The request is preserved in the collection to prevent accidental or unintentional data loss.
Only applies when you sync changes from a specification to a collection.
Changes in a specification may overwrite the changes in a collection. All changes to the collection are lost in this scenario. It’s recommended that you don’t apply changes to the specification and collection at the same time to prevent data loss.
The following exceptions apply:
No. Updating the name of a specification and syncing it to its generated collection won’t update the name of the generated collection. The name of a collection is generated only at the time of creating it and remains unchanged thereafter to prevent introducing a breaking change to the mapping.
Yes. During a two-way sync, Postman preserves any JSON schema keywords present in the OpenAPI 3.1 specification, even if they’re not supported by collection types. These properties are restored when syncing back, ensuring no schema data is lost.
type keyword when it’s defined as an array in OpenAPI 3.1?OpenAPI 3.1 lets you define the type keyword as an array, but Postman Collections only support a single type value. During two-way sync, Postman preserves the original type array from the specification and restores it when syncing changes back, ensuring that no type information is lost.