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

Question

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 :
- openapi-diff
- quen2404/openapi-diff
- Azure/openapi-diff
- ...
( 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

Answer 1

I just wrote this OAS diff tool in golang: https://github.com/Tufin/oasdiff
It outputs json like this:
{
"spec": {
"paths": {
"modified": {
"/": {
"operations": {
"modified": {
"POST": {
"servers": {
"added": [
"https://app.amberflo.io/ingest-endpoint"
],
"deleted": [
"https://app.amberflo.io/ingest"
]
}
}
}
},
"servers": {
"added": [
"https://app.amberflo.io/ingest-endpoint"
],
"deleted": [
"https://app.amberflo.io/ingest"
]
}
}
}
},
"servers": {
"added": [
"https://app.amberflo.io/ingest-endpoint"
],
"deleted": [
"https://app.amberflo.io/ingest"
]
}
},
"summary": {
"diff": true,
"components": {
"paths": {
"modified": 1
},
"servers": {
"added": 1,
"deleted": 1
}
}
}
}

Answer 2

My own answer :
name: 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#1.0.10-4.2.3
- name: Set up env variables
run: |
echo "::set-env name=CURRENT_BRANCH::$(echo ${{ github.head_ref }} | sed 's|.*/||')"
echo "::set-env name=TARGET_BRANCH::$(echo ${{ github.base_ref }} | sed 's|.*/||')"
- name: Clone repository in branch ${{ env.TARGET_BRANCH }}
uses: actions/checkout#v2
with:
path: 'A'
ref: ${{ github.base_ref }}
- name: Clone repository in branch ${{ env.CURRENT_BRANCH }}
uses: actions/checkout#v2
with:
path: '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" )"
echo "::set-env name=SPECS_LOG::$(echo "$(pwd)/breaking-changes.log" )"
echo "::set-env name=JSON_DIFF_FILE::$(echo "$(pwd)/breaking-changes.json" )"
echo "::set-env name=GH_COMMENT_FILE::$(echo "$(pwd)/Github-comment.md" )"
# 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 }} | tee ${{ env.SPECS_LOG }}
sed -n '1!p' ${{ env.SPECS_LOG }} > ${{ env.JSON_DIFF_FILE }}
- uses: actions/upload-artifact#v1
with:
name: openapi-diff.json
path: breaking-changes.json
- name: Prepare comment on Github PR
run: |
sed -n '1p' ${{ env.SPECS_LOG }} >> ${{ env.GH_COMMENT_FILE }}
printf "\n\n\`\`\`yaml\n" >> ${{ env.GH_COMMENT_FILE }}
sed -n '1!p' ${{ env.SPECS_LOG }} >> ${{ env.GH_COMMENT_FILE }}
printf "\n\`\`\`\n" >> ${{ env.GH_COMMENT_FILE }}
- name: comment PR
uses: machine-learning-apps/pr-comment#master
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
with:
path: Github-comment.md