How Postman Uses the OpenAPI Specification


This is a follow-up to our recent post about Postman joining the OpenAPI Initiative (OAI). You can read the full announcement here.

At Postman, our mission is to encourage creativity by providing user-friendly tools that help people create innovative software. APIs are a big part of how software is built today, and we’ve been closely following the trends around the API ecosystem—including the OpenAPI Specification (OAS)—for the last six years to help us pursue this mission.

As part of this pursuit, we’ve been keenly listening to our customers and making regular improvements to our support for various schema formats: We started with Swagger 2.0 in 2015, and we recently added support for OAS because we noticed increasing adoption of the specification and how it unlocks new possibilities.

In particular, we addressed challenges in four specific workflow use cases that involve OAS and have made a big difference for our users.

Use case #1: Validating and syncing during development

We noticed a recurring workflow in which many of our users would import their OAS documents into Postman, convert them to collections, and proceed to use Postman for mocking, monitoring, and publishing documentation. The issue? When updating the schema, users were required to recreate their collections (and any associated mocks and monitors). To simplify and streamline this process, we introduced support for validating and syncing collections with their linked API specification so that users don’t have to recreate assets. With this capability, you’re free to update your collection or OAS document, and Postman will alert you if any change you make creates an incongruity with your specification. (You can also choose to fix your collection automatically by selecting in Postman to apply the feedback given as part of validation.) In short, any new operations added to your schema can now be automatically incorporated into your collection with a single click!

A detailed walk-through is available here.

Validating OpenAPI specifications during development with Postman
Postman alert showing incongruity with a specification upon change to a collection

Use case #2: Validating API responses

Another use case we realized we needed to address was the lack of validation of API responses against the linked schemas. Since Postman v7.15, any request made from a collection that has an associated schema—including OAS schemas—is automatically validated. This means that Postman will instantly highlight any discrepancies between your schema and the actual API response. This workflow is critical for faster debugging and a shorter time to production.

A detailed walk-through is available here.

Validating OpenAPI specifications for your API responses with Postman
Example of schema validation highlighting discrepancies with OAS

Use case #3: Organizing with tags

In the past, requests in Postman Collections could only be grouped by the URL path. After Postman users pointed out the use of tags in OpenAPI Specification documents to organize endpoints and operations, we decided to integrate this helpful function. So with the release of Postman v7.25, users can utilize the OpenAPI Specification’s ‘tags’ feature to better organize their collections.

Using the OpenAPI tag feature in Postman
Postman collection organized using the OpenAPI Specification’s ‘tags’ feature

Use case #4: Providing support for multi-file schemas

Since we observed that developers often split larger schemas into multiple files for better readability and composability, we wanted to accommodate that trend. Postman now supports importing these multi-file schemas, enabling a more seamless API workflow. You can select an entire folder that contains a single schema split across multiple files, and Postman will stitch them back together into a single API schema.

If you haven’t already yet, download Postman to see how we’re supporting the OpenAPI Specification for better API development. With Postman joining the OpenAPI Initiative to help the spec evolve, we’ll continue looking to our users to learn what the community wants to see next.

What do you think about this topic? Tell us in a comment below.


Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

7 thoughts on “How Postman Uses the OpenAPI Specification

  • Avatar

    I would like to see the ability to generate a Swagger 2.0 or OAS spec from a collection. I currently have to take the collection export to APImatic to do this, so it would be great to be able to finish that work flow all within Postman. “Export Collection as Swagger 2.0/OAS”


  • Avatar

    I fully second what Mike said below, being able to export an OpenAPI spec from a Postman collection would be incredibly useful!

  • Avatar

    I second (or third…) what Mike and Ewa said. Your competitors have the essential capability to export to OpenAPI.

  • Avatar

    Yes, please, exporting into OpenAPI/Swagger instead of using APIMatic.

  • Avatar

    Without being able to export to OpenAPI, your product is quite useless.

  • Avatar

    It’d be great to support looking for references in the surrounding folder / hinting in the UI that multi-file support exists – I was used to passing the root spec file to a cli tool, so I just assumed it was unsupported today.

    Glad y’all are working on OpenAPI support!