How Postman Uses the OpenAPI Specification

Abhijit Kane

July 27, 2020

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.

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.

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.

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.