Sync your specs 😎

Some development teams that work with API description formats like RAML, Swagger, or API Blueprint want to know how those formats work with Postman collections.

 

With the Import button, the Postman app makes it easy to import data and work with your API description format of choice. If you’re using the OpenAPI Specification, for example, you can import the Swagger file (v1 or v2) directly into Postman and convert it to an actionable Postman collection. Let’s try it out using this sample Swagger v2.0 file.

The workflow using the Postman app is simple, and requires a single import:

This is helpful for development, but what if you want to update your Postman collections every time your API description file changes? Instead of updating the collection manually, let’s automate this process using a format converter and the Postman API.

The workflow using an automation script looks like this:

Convert Swagger to Postman

Before we begin, make sure you have Node.js and a package manager like npm installed on your machine. This example uses Node, but you could use your favorite scripting setup.

There are a number of tools available for converting various API description formats. In this example, we will use an open-source project from Postman called swagger2-postman2-converter. This converter translates and preserves schema elements like folders, sample request bodies, responses, and authentication helpers.

Let’s create a script to convert the Swagger 2.0 format to Postman 2.0. 

Install the dependencies from the command line.

Let’s run our script converter.js.

You should see a new file in your directory called postman-collection.json. Now that we have the data in a usable Postman collection format, the next step is to update our Postman collection.

Update Postman collection

Now it’s time to update our Postman collection using the Postman API. If you don’t already have a Postman API key, get a key from the integrations dashboard.

  • Use the Postman API’s GET All Collections request to find your collection's uid and id. If you’re following along with this example, you can import the Postman collection file into the Postman app to create the Postman collection as we did earlier, create a new collection in the app, or use another one of your existing collections.
  • In this example, I created a file called config.js as a way to establish a relationship between my Postman collections and the converted files that I’ll be using to update those collections. However, you could also write a few custom lines of code to accommodate your individual setup and naming convention.
  • Make a few adjustments to the Postman collection file. The full code sample is shown below.
    • Add a new collection property to wrap the existing JSON.
    • Update the collection.info.id property with our collection_id from Step 1.
    • Add a new collection.info._postman_id property with the same value as collection.info.id.
  • Use the Postman API’s PUT Update Collection request to update your collection using the Postman collection v2 format. Make sure to add {format="2.1.0"} as a URL parameter. For this step, remember that you can build your request in Postman using the Postman API collection, test and inspect it in Postman, and then generate a snippet of code in your preferred language or framework when you’re ready to add it to your script.

Try it yourself

Here’s an example of a handy dandy script, and if you don't feel like writing a lick of code, try it out from the example repository.

Install your new dependencies. Then, if you run the full script, you should see a successful response:

This is an easy way to programmatically update your Postman collections.

More food for thought:

        • If you’re maintaining your specification in a platform like GitHub, use a webhook to detect when a file has changed to trigger the update to Postman.
        • If you’re using Postman as the single source of truth for your API documentation, you might be including descriptions in markdown and screenshots. So that you’re not overwriting all of these updates every time you update a collection using the Postman API, you can GET Single Collection to compare the differences between the latest spec and the collection, before reconciling those differences and updating the collection.

 

Author: joyce

Developer Evangelist. Makes dank memes.

  • Roman (Redeyes)

    Seems not work properly:

    rMethod = pathItem.method,
    ^
    TypeError: Cannot read property 'method' of undefined
    at Object.convertSwaggerRequestToItem (C:UsersRedeyesnode_modulesswagger2-postman2-converterlibhelpers.js:149:26)