Github Actions - Compare and find differences between two OAS V3 files

Suppose you are given two OpenApi Specification (OAS) V3 files :

  • original-spec.yaml : The original spec
  • modified-spec.yaml : The modified ( with enhancement / breaking changes / etc )

( an example of both files is available on https://gist.github.com/jy95/d7b53648eb756547eb67fd0db962f68d )

I would like to find a CLI tool that will generates an human readable report
( that I could ,for example, upload it in a PR comment with PR Comment from File
)

My requirements are the following ones :

  • no technical restriction ( you are free to use any programming language library as long as it
    works , including using a OAS to Swagger v2 converter if needed )

  • human readable / comprehensible ( it should be clear so that people that don’t know OAS aren’t lost )

  • maintained ( not mandatory but it is better )

Currently I found these projects on the web :

( others undoubtedly exist: I leave it to you to find some / or to help me pick one that’s good enough… )

Here is the start of a Github workflow to help you kickstart :

name: API Breaking Changes
# Everyone is happy with breaking changes ^^
on:
  pull_request:

jobs:
  build-report:
    needs: build-oas-artefacts
    runs-on: ubuntu-latest
    steps:
      - name: Download OAS file from SOURCE branch
        uses: actions/download-artifact@v1
        with:
          name: original-spec.yaml
      - name: Download OAS file from TARGET branch
        uses: actions/download-artifact@v1
        with:
          name: modified-spec.yaml

Thanks for the help

Hi @jy95 ,

Glad to see you in Github Community Forum!

  1. Github actions only supports Github Free, Pro, Enterprise…etc but not Github Gist, please put the two OAS V3 files directly in github. Or you can checkout the gist content with ‘git clone’ command, but any change in Gist won’t trigger the github event.

  2. You have to upload the artifacts fistly then download it in the workflow, cannot directly use download-artifact action, please refer to the artifacts usage sample for reference.

  3. Github hosted runner are based on Azure VM, and [Azure/openapi-diff] looks an official one from Auzre, you can try it to compare the two yaml files.

Thanks.

To anyone interessed , here is my solution ( adapt it for your favorite tool ) : 

name: Source Code API Breaking Changes
# Everyone is happy with breaking changes ^^
on:
  pull_request:

jobs:
  build-oas-artefacts:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v1
        with:
          node-version: '12.x'
      - name: Install required tools
        run: |
          npm install speccy -g
          npm install -g @openapitools/openapi-generator-cli
      - name: Set up env variables
        run: |
          echo "::set-env name=CURRENT_BRANCH::$(echo ${{ github.base_ref }} | sed 's|.*/||')"
          echo "::set-env name=TARGET_BRANCH::$(echo ${{ github.head_ref }} | sed 's|.*/||')"
      - name: Clones repository with the two separate branch ( ${{ env.CURRENT_BRANCH }} and ${{ env.TARGET_BRANCH }})
        run: |
          git clone -b ${{ env.TARGET_BRANCH }} --depth 1 --single-branch https://github.com/${{ github.repository }}.git A
          git clone -b ${{ env.CURRENT_BRANCH }} --depth 1 --single-branch https://github.com/${{ github.repository }}.git B
      - name: Check if OAS from ${{ env.CURRENT_BRANCH }} is valid
        run: |
          npx openapi-generator validate -i B/api.yml
      - name: Check if OAS from ${{ env.TARGET_BRANCH }} is valid
        run: |
          npx openapi-generator validate -i A/api.yml
      - name: Build OAS specifications
        run: |
          npx speccy resolve A/api.yml -o original-spec.yaml
          npx speccy resolve B/api.yml -o modified-spec.yaml
      - name: Upload single OAS file from ${{ env.TARGET_BRANCH }}
        uses: actions/upload-artifact@v1
        with:
          name: original-spec.yaml
          path: original-spec.yaml
      - name: Upload single OAS file from ${{ env.CURRENT_BRANCH }}
        uses: actions/upload-artifact@v1
        with:
          name: modified-spec.yaml
          path: modified-spec.yaml
  build-report:
    needs: build-oas-artefacts
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v1
        with:
          node-version: '13.x'
      - name: Install required tools
        run: |
          npm install openapi-diff -g
      - name: Download OAS file from SOURCE branch
        uses: actions/download-artifact@v1
        with:
          name: original-spec.yaml
          path: specs/
      - name: Download OAS file from TARGET branch
        uses: actions/download-artifact@v1
        with:
          name: modified-spec.yaml
          path: specs/
      - name: Set up env variables
        run: |
          echo "::set-env name=ORIGIN_SPEC::$(echo "$(pwd)/specs/original-spec.yaml" )"
          echo "::set-env name=MODIFIED_SPEC::$(echo "$(pwd)/specs/modified-spec.yaml" )"
# See : https://github.com/actions/download-artifact/issues/14
      - name: Restore permissions
        run: |
          chmod -R 777 ${{ env.ORIGIN_SPEC }}
          chmod -R 777 ${{ env.MODIFIED_SPEC }}
      - name: Generate report
        run: |
          openapi-diff ${{ env.ORIGIN_SPEC }} ${{ env.MODIFIED_SPEC }} > breaking-changes.log
          sed -n '1!p' breaking-changes.log > breaking-changes.json
      - uses: actions/upload-artifact@v1
        with:
          name: openapi-diff.json
          path: breaking-changes.json

  

1 Like

Small mistake I have done.
Replace :

> breaking-changes.log

By :

| tee breaking-changes.log
2 Likes

Not sure this is exactly what you are looking for, but I ended up with the set up details in this gist :

My use case was mostly to compare a OAS file in a PR against the base branch , but you could probably adapt it.

In this case, my workflow is to post a comment in the open PR containing the list of changes, and if it should be considered breaking , in a nice markdown format , based on https://github.com/quen2404/openapi-diff