Beppe is Here
Pushing OpenAPI files to Postman

Photo by Timon Studler on Unsplash

Pushing OpenAPI files to Postman

Seamless integration with a GitHub action

Beppe Catanese's photo
Beppe Catanese
·

5 min read

For the OpenAPI adopters, the OpenAPI specification is the source of truth. The specification is the contract we offer to our APIs' consumers. It can be published as documentation but also consumed by other tools to provide additional value in terms of developer experience (think of an API dashboard or SDK generation), collaboration (shared on Postman) or testing (mocks and contract testing).

In this article…

..read how an OpenAPI file can be converted in a Postman collection and, using a Github workflow, pushed seamlessly to postman.com. Checkout the different steps involved and eventually build your own workflow.

The use case

You are a spec-first developer in an API-first organisation. You build in public and make your API contracts available on GitHub. Additionally, you provide updated Postman collections to empower API consumers in their exploration, adoption and integration.

You understand that manual tasks are both laborious and prone to errors, which can be detrimental when striving for speed, efficiency and scalability. You don’t want to automate, you need to.

The automated conversion from OpenAPI to Postman ensures the alignment between the tools you provide and the API specification. There’s no room for discrepancies, and your investment in a well-crafted OpenAPI design, that includes reusable objects and multiple examples, pays off.

Seamlessly publishing the Postman collections ensures your audience has the necessary tools and resources as quickly as possible.

This approach leads to less effort and greater speed. Let’s see how it can be implemented.

The GitHub workflow

The GitHub workflow includes 3 steps:

  • checkout the repository

  • generate the Postman collection as JSON

  • push the JSON file to your Postman workspace

Below you can find the entire workflow file. In the upcoming sections, we look at what each step entails.

name: "From OpenAPI file to Postman"

on:
  workflow_dispatch:
    inputs:
      file:
        description: 'OpenAPI filepath'     
        required: true
        default: 'test/openapi/test.yml'
jobs:
  generate:
    name: "Generate Postman Collection"
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo    
        uses: actions/checkout@v3
        with:
          fetch-depth: 2
      - name: Generate postman.json    
        uses: addnab/docker-run-action@v3
        with:
          image: openapitools/openapi-generator-cli
          options: -v ${{ github.workspace }}:/local
          run: |
            echo "Generate postman.json from ${{ github.event.inputs.file }}"
            /usr/local/bin/docker-entrypoint.sh generate -i /local/${{ github.event.inputs.file }} -g postman-collection -o /local/out
      - name: Push to Postman    
        uses: gcatanese/push-to-postman-action@main
        with:
          goal: createOrUpdate
          postman-key: ${{ secrets.POSTMAN_API_KEY }}
          postman-file: ${{ github.workspace }}/out/postman.json
          workspace-id: ${{ secrets.POSTMAN_WORKSPACE_ID }}

Inputs and variables

First of all, let’s see which are the inputs that the workflow requires. In this example, we assume running the workflow manually( workflow_dispatch ) so we are going to provide, as input, the path of the OpenAPI file.

Being mandatory, it must be provided before running the workflow, and it can be used using the notation ${{ github.event.inputs.file }} .

We also need the variables that define settings like the Postman API key and the Postman workplace ID. Those are configured as repository secrets and can be used using the notation ${{ secrets.POSTMAN_API_KEY }} and ${{ secrets.POSTMAN_WORKSPACE_ID }} .

Checkout the repository

This first step checks out the repository. In this example (and probably in most cases) the files to process are part of the repository, therefore the checkout step makes sure the workflow can access them.

Generate Postman JSON file

The second step is probably the most interesting one. From the OpenAPI file, it generates a Postman collection in JSON format, according to the Postman JSON format v2.1.0.

This JSON generation is performed using the OpenAPI Generator, a popular open-source project that can generate code (in many different languages, client and server-side) starting from an OpenAPI specification.

In a nutshell:

  • generates code from an OpenAPI file

  • supports 100+ languages

  • can be run from CLI, Docker or Java jar

  • open-source and extendible

Check out my other blog if you are interested in more details and samples.

Postman OpenAPI Generator

Thankfully, the OpenAPI Generator supports also the Postman format, which I created and contributed 😃 to the project some time ago.

During the generation, the following happens:

  • each endpoint in the OpenAPI specification becomes a folder in the collection

  • each request example becomes a Postman request in the collection

  • security schemes (API key, basic authentication) are configured in the collection

  • any placeholder in the JSON request example (i.e. {{MY_VAR}}) is defined as a collection variable

  • optionally path parameters can also be defined as collection variables

Using the Docker Run Action we can run the OpenAPI Generator Docker image as part of the GitHub workflow and create the postman.json file.

- name: Generate postman.json    
  uses: addnab/docker-run-action@v3
  with:
    image: openapitools/openapi-generator-cli
    options: -v ${{ github.workspace }}:/local
    run: |
      echo "Generate postman.json from ${{ github.event.inputs.file }}"
      /usr/local/bin/docker-entrypoint.sh generate -i /local/${{ github.event.inputs.file }} -g postman-collection -o /local/out

Interesting to note above:

-i indicates the path to the OpenAPI file

-g defines which generator should run (postman-collection )

-o sets the location of the generated JSON file

Push to Postman

The final step is accomplished using the Push To Postman GitHub action.

The action pushes postman.json files to Postman, creating or updating collections.

Push to Postman action on GitHub Action marketplace — image by author

We will use the createOrUpdate goal so we can cover both create and update, without worrying if the collection already exists.

- name: Push to Postman    
        uses: gcatanese/push-to-postman-action@main
        with:
          goal: createOrUpdate
          postman-key: ${{ secrets.POSTMAN_API_KEY }}
          postman-file: ${{ github.workspace }}/out/postman.json
          workspace-id: ${{ secrets.POSTMAN_WORKSPACE_ID }}

Conclusion

The article has covered how leading technologies, like OpenAPI and Postman, can be used together to streamline development workflows and ensure consistency between documentation and implementation.

Thanks to GitHub CI capabilities, this workflow can be automated, resulting in a dual benefit: it boosts developer productivity on the one hand and enhances the overall API consumer experience on the other.

Furthermore, there are additional scenarios worth exploring. For instance, automating the validation and testing of the API by executing the auto-generated Postman collection test cases.

Stay tuned for emerging tools and evolving best practices in the dynamic API ecosystem. Continuously iterating and refining your processes is the key to delivering outstanding APIs.

PostmanGitHubgithub-actions