tsimbalar/README.md

## README.md

      
    Raw
  

              README.md
            
          
    I couldn't get https://github.com/evereepay/openapi-diff-action to work for me, so ended up doing it a bit more manually, by invoking directly https://github.com/quen2404/openapi-diff and generating a comment for the PR with https://github.com/actions/github-script
To do that you need :

the script check-openapi-diff.sh ... in my case it is in the .ci folder at the root of our repo
the GitHub Actions workflow openapi.yaml. It needs to be under the folder .github/workflows of the repo
possibly adapt some paths here and there in the openapi.yaml file

If everything goes well, you'll get comments on you PRs such as :

API Diff Report

❌ BREAKING CHANGES ‼️

ℹ️ This is not preventing you from merging, you are an adult.
What's Changed


POST /v1/enrollments

Request:

Changed content type : application/json
New required properties:

thisIsANewRequiredProp


Added property thisIsANewRequiredProp (boolean)


comparing /home/runner/work/xxxx/xxxx/base/docs/swagger.yaml with /home/runner/work/xxxx/xxxxx/head/docs/swagger.yaml.

or

API Diff Report

✅ CHANGES - non breaking 👌

ℹ️ This is not preventing you from merging, you are an adult.
What's Changed


POST /v2/enrollments

Request:

Changed content type : application/json

Added property newOptionalProp (string)


comparing /home/runner/work/xxxx/xxx/base/docs/swagger.yaml with /home/runner/work/xxxx/xxxx/head/docs/swagger.yaml.

or

API Diff Report

⚪ NO API changes 👻

ℹ️ This is not preventing you from merging, you are an adult.

comparing /home/runner/work/xxxx/xxxx/base/docs/swagger.yaml with /home/runner/work/xxxx/xxxx/head/docs/swagger.yaml.

  
## check-openapi-diff.sh
#!/bin/sh
set -e

#
# Runs the openapi-diff tool from https://github.com/quen2404/openapi-diff to detect changes against the base branch of the PR
#
# Used in CI pipelines to report possible breaking changes
#

if [ -z "$1" ]; then
  echo "🛑You need to provide the original spec file path"
  exit 1
fi

if [ -z "$2" ]; then
  echo "🛑You need to provide the new spec file path"
  exit 1
fi

BASE_SPEC_PATH="$1"
HEAD_SPEC_PATH="$2"
OUTPUT_DIR="$(mktemp -d -t openapi-diff-result-XXXXXXXXXX)"

# Run diff
RESULT=$(docker run --rm -v "$BASE_SPEC_PATH:/base.yaml:ro" -v "$HEAD_SPEC_PATH:/head.yaml:ro" -v "$OUTPUT_DIR:/output" quen2404/openapi-diff /base.yaml /head.yaml --markdown /output/out.md --state)

# result is `no_changes` or `incompatible` or `compatible`

echo "## _API Diff Report_"

echo
if [ "$RESULT" = "incompatible" ]; then
  echo "### :x: **BREAKING CHANGES** :bangbang:"
elif [ "$RESULT" = "compatible" ]; then
  echo "### :white_check_mark: **CHANGES - non breaking** :ok_hand:"
elif [ "$RESULT" = "no_changes" ]; then
  echo "### :white_circle: **NO API changes** :ghost:"
else
  echo "### :warning: Unexpected result from diff \`$RESULT\`"
fi

echo
echo ":information_source: This is not preventing you from merging, you are an adult."
echo

cat "$OUTPUT_DIR/out.md"

echo "---"
echo "comparing \`$BASE_SPEC_PATH\` with \`$HEAD_SPEC_PATH\`."

## openapi.yaml

name: openapi

on:
  pull_request:
    paths:
      - 'docs/*.yaml'

jobs:
  openapi-diff:
    runs-on: ubuntu-20.04
    steps:
    - name : Print GitHub context (for debug)
      env:
        GITHUB_CONTEXT: ${{ toJson(github) }}
      run: echo "$GITHUB_CONTEXT"
    - name: Check out HEAD revision
      uses: actions/checkout@v2
      with:
        ref: ${{ github.head_ref }}
        path: head
    - name: Check out BASE revision
      uses: actions/checkout@v2
      with:
        ref: ${{ github.base_ref }}
        path: base
    - name: Check for OpenAPI changes
      id: openapi_diff
      run: |
        OPEN_API_DIFF_REPORT=$(head/.ci/check-openapi-diff.sh "$(pwd)/base/docs/swagger.yaml" "$(pwd)/head/docs/swagger.yaml")
        echo 'DIFF_REPORT_MARKDOWN<<EOF' >> $GITHUB_ENV
        echo "$OPEN_API_DIFF_REPORT" >> $GITHUB_ENV # Double quotes are needed to preserve new lines.
        echo 'EOF' >> $GITHUB_ENV
    - name: Add Diff as PR Comment
      uses: actions/github-script@v2.0.0
      with:
        github-token: ${{ secrets.GITHUB_TOKEN }}
        script: |
          github.issues.createComment({
            issue_number: context.issue.number,
            owner: context.repo.owner,
            repo: context.repo.repo,
            body: process.env.DIFF_REPORT_MARKDOWN
          })
	#!/bin/sh
	set -e

	#
	# Runs the openapi-diff tool from https://github.com/quen2404/openapi-diff to detect changes against the base branch of the PR
	#
	# Used in CI pipelines to report possible breaking changes
	#

	if [ -z "$1" ]; then
	echo "🛑You need to provide the original spec file path"
	exit 1
	fi

	if [ -z "$2" ]; then
	echo "🛑You need to provide the new spec file path"
	exit 1
	fi

	BASE_SPEC_PATH="$1"
	HEAD_SPEC_PATH="$2"
	OUTPUT_DIR="$(mktemp -d -t openapi-diff-result-XXXXXXXXXX)"

	# Run diff
	RESULT=$(docker run --rm -v "$BASE_SPEC_PATH:/base.yaml:ro" -v "$HEAD_SPEC_PATH:/head.yaml:ro" -v "$OUTPUT_DIR:/output" quen2404/openapi-diff /base.yaml /head.yaml --markdown /output/out.md --state)

	# result is `no_changes` or `incompatible` or `compatible`

	echo "## _API Diff Report_"

	echo
	if [ "$RESULT" = "incompatible" ]; then
	echo "### :x: BREAKING CHANGES :bangbang:"
	elif [ "$RESULT" = "compatible" ]; then
	echo "### :white_check_mark: CHANGES - non breaking :ok_hand:"
	elif [ "$RESULT" = "no_changes" ]; then
	echo "### :white_circle: NO API changes :ghost:"
	else
	echo "### :warning: Unexpected result from diff \`$RESULT\`"
	fi

	echo
	echo ":information_source: This is not preventing you from merging, you are an adult."
	echo

	cat "$OUTPUT_DIR/out.md"

	echo "---"
	echo "comparing \`$BASE_SPEC_PATH\` with \`$HEAD_SPEC_PATH\`."

	name: openapi

	on:
	pull_request:
	paths:
	- 'docs/*.yaml'

	jobs:
	openapi-diff:
	runs-on: ubuntu-20.04
	steps:
	- name : Print GitHub context (for debug)
	env:
	GITHUB_CONTEXT: ${{ toJson(github) }}
	run: echo "$GITHUB_CONTEXT"
	- name: Check out HEAD revision
	uses: actions/checkout@v2
	with:
	ref: ${{ github.head_ref }}
	path: head
	- name: Check out BASE revision
	uses: actions/checkout@v2
	with:
	ref: ${{ github.base_ref }}
	path: base
	- name: Check for OpenAPI changes
	id: openapi_diff
	run: \|
	OPEN_API_DIFF_REPORT=$(head/.ci/check-openapi-diff.sh "$(pwd)/base/docs/swagger.yaml" "$(pwd)/head/docs/swagger.yaml")
	echo 'DIFF_REPORT_MARKDOWN<<EOF' >> $GITHUB_ENV
	echo "$OPEN_API_DIFF_REPORT" >> $GITHUB_ENV # Double quotes are needed to preserve new lines.
	echo 'EOF' >> $GITHUB_ENV
	- name: Add Diff as PR Comment
	uses: actions/github-script@v2.0.0
	with:
	github-token: ${{ secrets.GITHUB_TOKEN }}
	script: \|
	github.issues.createComment({
	issue_number: context.issue.number,
	owner: context.repo.owner,
	repo: context.repo.repo,
	body: process.env.DIFF_REPORT_MARKDOWN
	})