oasdiff / oasdiff-action Goto Github PK

View Code? Open in Web Editor NEW

34.0 34.0 21.0 66 KB

GitHub action for comparing and detect breaking changes in OpenAPI specs

License: Apache License 2.0

Dockerfile 4.45% Shell 95.55%

oasdiff-action's Introduction

Command-line and Go package to compare and detect breaking changes in OpenAPI specs.

Installation

Install with Go

go install github.com/tufin/oasdiff@latest

Install on macOS with Brew

brew tap tufin/homebrew-tufin
brew install oasdiff

Install on macOS and Linux using curl

curl -fsSL https://raw.githubusercontent.com/tufin/oasdiff/main/install.sh | sh

Manually install on macOS, Windows and Linux

Copy binaries from latest release

Try it

Locally

oasdiff changelog https://raw.githubusercontent.com/Tufin/oasdiff/main/data/openapi-test1.yaml https://raw.githubusercontent.com/Tufin/oasdiff/main/data/openapi-test5.yaml

With Docker

docker run --rm -t tufin/oasdiff changelog https://raw.githubusercontent.com/Tufin/oasdiff/main/data/openapi-test1.yaml https://raw.githubusercontent.com/Tufin/oasdiff/main/data/openapi-test5.yaml

Features

Detect breaking changes
Display a user-friendly changelog of all important API changes
Generate comprehensive diff reports including all aspects of OpenAPI Specification: paths, operations, parameters, request bodies, responses, schemas, enums, callbacks, security etc.
Output reports in YAML, JSON, Text, Markdown, HTML, JUnit XML or the github actions annotation format
Compare local files or remote files over http/s
Compare specs in YAML or JSON format
Compare two collections of specs
API deprecation
API stability levels
Multiple versions of the same endpoint
Merge allOf schemas
Merge common parameters
Case-insensitive header comparison
Path prefix modification
Path parameter renaming
Excluding certain kinds of changes
Tracking changes to OpenAPI Extensions
Filtering endpoints
Extending breaking changes with custom checks
Localization: display breaking changes and changelog messages in English or Russian (please contribute support for your language)
Customize with configuration files
Run from Docker
Integrate in GitHub
GitHub Action
Cloud Service
OpenAPI Sync: Get notified when an API provider breaks the API
Embed in your go program

Demo

The main commands

diff: the diff between OpenAPI specs, fully detailed
breaking: breaking changes between OpenAPI specs
changelog: important changes between OpenAPI specs including breaking and non-breaking changes
flatten: replace all instances of allOf by a merged equivalent
checks: displays the different checks that oasdiff runs to detect changes

Credits

This project relies on the excellent implementation of OpenAPI 3.0 for Go: kin-openapi.

Feedback

We welcome your feedback.
If you have ideas for improvement or additional needs around APIs, please let us know.

oasdiff-action's People

Contributors

Stargazers

Watchers

oasdiff-action's Issues

Any plans to support `--flatten-allof` for this GH action

Hi,

First thanks for the awesome GH action, any plans to support --flatten-allof to be set via action? this is a pretty hand config https://github.com/Tufin/oasdiff/blob/main/ALLOF.md

Show breaking changes inline in the OpenAPI document

This enhancement is to show the oasdiff breaking changes inline with the OpenAPI document where they occur. This will make it easier for people reviewing a PR to see where the breaking changes are.

Here is an example from the Spectral Action that shows ruleset errors right in the OpenAPI document:

breaking output limited to one line

I've seen #35 but still, what is the purpose of that head?

Breaking output is different than diff or changelog. I would like to use that output in the PR comment. Could this be changed?

Support `--exclude-elements`

the original oasdiff tool supports --exclude-elements
https://github.com/oasdiff/oasdiff#excluding-specific-kinds-of-changes

it will be cool if oasdiff-action also supports the flag, as it allows users to exclude certain elements like title/description in detecting changes.

Getting an error 'Error: Unable to process file command 'output' successfully.' when running oasdiff/oasdiff-action/diff@main from main.

Hi,

When we are running the diff check from the main branch we are getting the errors below:
10running oasdiff diff base: specs/original-spec.yaml, revision: specs/modified-spec.yaml, format: text, fail_on_diff: true, include_path_params: false, exclude_elements: , composed: false, output_to_file: 11flags: --format text --fail-on-diff 12Error: Unable to process file command 'output' successfully. 13Error: Invalid value. Matching delimiter not found 'a48a4f97a1a9457eb4dd8bb5332a6f3c'

To fix it we set the version v.0.0.16 and it worked:
oasdiff/oasdiff-action/[email protected] from oasdiff/oasdiff-action/diff@main

Let me know if additional details are needed.
Thanks,

Problem downloading the action

I didn't change anything in my workflow but now receive this weird error:

Download action repository 'oasdiff/oasdiff-action@main' (SHA:d67398257eaf22e1bd9dffb33c53fed2344e7185)
Error: Can't find 'action.yml', 'action.yaml' or 'Dockerfile' for action 'oasdiff/oasdiff-action/check-breaking@main'.

Here is the part that use your github action:

      - name: Running OpenAPI Spec diff action
        id: test_breaking_changes
        uses: oasdiff/oasdiff-action/check-breaking@main
        with:
          base: 'openapi.old.yaml'
          revision: 'openapi.yaml'
          fail-on-diff: true

Do you know if anything could have change on your side?

breaking output only shows one line

The output of breaking its showing only one line.

This is the result

The desired result

Error: failed to load base spec from <base> with error converting YAML to JSON: yaml: unmarshal errors

Despite locally it works perfectly with .deb from https://github.com/Tufin/oasdiff/releases/tag/v1.9.6 and same base and rev files, in GitHub Action I get:

Error: failed to load base spec from "openapi/oh.yaml" with error converting YAML to JSON: yaml: unmarshal errors:
  line 7991: mapping key "empty" already defined at line 7980
  line 8048: mapping key "empty" already defined at line 8037
  line 8107: mapping key "empty" already defined at line 8096
  line 8159: mapping key "empty" already defined at line 8148
  line 8216: mapping key "empty" already defined at line 8205
  line 8287: mapping key "empty" already defined at line 8276
  line 8344: mapping key "empty" already defined at line 8333

https://github.com/mwithi/openhospital-api/actions/runs/6936878852/job/18869869828#step:12:15

base: oh.yaml.txt (link)
rev: oh_rev.yaml.txt (link)

Note: I'm using my fork inspired by #19, but the error is the same with oasdiff/oasdiff-action/breaking@main

error messages broken in v0.0.18

v0.0.18 Github Actions log

2024-03-11T08:52:37.7408030Z ##[group]Run oasdiff/oasdiff-action/breaking@main
2024-03-11T08:52:37.7408818Z with:
2024-03-11T08:52:37.7409271Z   base: https://<hostname>/api-docs/v4/api.yaml
2024-03-11T08:52:37.7409896Z   revision: public/api-docs/v4/api.yaml
2024-03-11T08:52:37.7410381Z   fail-on-diff: true
2024-03-11T08:52:37.7410747Z   include-path-params: false
2024-03-11T08:52:37.7411476Z   composed: false
2024-03-11T08:52:37.7412136Z ##[endgroup]
2024-03-11T08:52:37.7743142Z ##[command]/usr/bin/docker run --name c9619df23929694ff45629b34a89e2c750a48_3fda30 --label 3c9619 --workdir /github/workspace --rm -e "INPUT_BASE" -e "INPUT_REVISION" -e "INPUT_FAIL-ON-DIFF" -e "INPUT_INCLUDE-CHECKS" -e "INPUT_INCLUDE-PATH-PARAMS" -e "INPUT_DEPRECATION-DAYS-BETA" -e "INPUT_DEPRECATION-DAYS-STABLE" -e "INPUT_EXCLUDE-ELEMENTS" -e "INPUT_COMPOSED" -e "INPUT_OUTPUT-TO-FILE" -e "HOME" -e "GITHUB_JOB" -e "GITHUB_REF" -e "GITHUB_SHA" -e "GITHUB_REPOSITORY" -e "GITHUB_REPOSITORY_OWNER" -e "GITHUB_REPOSITORY_OWNER_ID" -e "GITHUB_RUN_ID" -e "GITHUB_RUN_NUMBER" -e "GITHUB_RETENTION_DAYS" -e "GITHUB_RUN_ATTEMPT" -e "GITHUB_REPOSITORY_ID" -e "GITHUB_ACTOR_ID" -e "GITHUB_ACTOR" -e "GITHUB_TRIGGERING_ACTOR" -e "GITHUB_WORKFLOW" -e "GITHUB_HEAD_REF" -e "GITHUB_BASE_REF" -e "GITHUB_EVENT_NAME" -e "GITHUB_SERVER_URL" -e "GITHUB_API_URL" -e "GITHUB_GRAPHQL_URL" -e "GITHUB_REF_NAME" -e "GITHUB_REF_PROTECTED" -e "GITHUB_REF_TYPE" -e "GITHUB_WORKFLOW_REF" -e "GITHUB_WORKFLOW_SHA" -e "GITHUB_WORKSPACE" -e "GITHUB_ACTION" -e "GITHUB_EVENT_PATH" -e "GITHUB_ACTION_REPOSITORY" -e "GITHUB_ACTION_REF" -e "GITHUB_PATH" -e "GITHUB_ENV" -e "GITHUB_STEP_SUMMARY" -e "GITHUB_STATE" -e "GITHUB_OUTPUT" -e "RUNNER_OS" -e "RUNNER_ARCH" -e "RUNNER_NAME" -e "RUNNER_ENVIRONMENT" -e "RUNNER_TOOL_CACHE" -e "RUNNER_TEMP" -e "RUNNER_WORKSPACE" -e "ACTIONS_RUNTIME_URL" -e "ACTIONS_RUNTIME_TOKEN" -e "ACTIONS_CACHE_URL" -e "ACTIONS_RESULTS_URL" -e GITHUB_ACTIONS=true -e CI=true -v "/var/run/docker.sock":"/var/run/docker.sock" -v "/home/runner/work/_temp/_github_home":"/github/home" -v "/home/runner/work/_temp/_github_workflow":"/github/workflow" -v "/home/runner/work/_temp/_runner_file_commands":"/github/file_commands" -v "/home/runner/work/<repo>/<repo>":"/github/workspace" 3c9619:df23929694ff45629b34a89e2c750a48  "https://<hostname>/api-docs/v4/api.yaml" "public/api-docs/v4/api.yaml" "true" "" "false" "" "" "" "false" ""
2024-03-11T08:52:38.3154858Z running oasdiff breaking... base: https://<hostname>/api-docs/v4/api.yaml, revision: public/api-docs/v4/api.yaml, fail_on_diff: true, include_checks: , include_path_params: false, deprecation_days_beta: , deprecation_days_stable: , exclude_elements: , composed: false, output_to_file: 
2024-03-11T08:52:38.3170224Z flags:  --fail-on WARN
2024-03-11T08:52:40.5964966Z ##[error]Unable to process file command 'output' successfully.
2024-03-11T08:52:40.5983453Z ##[error]Invalid value. Matching delimiter not found '294217520dd1492ebded706d03a4add0'

v0.0.16 works fine.

2024-03-11T09:04:36.3778499Z ##[group]Run oasdiff/oasdiff-action/[email protected]
2024-03-11T09:04:36.3779388Z with:
2024-03-11T09:04:36.3780117Z   base: https://<hostname>/api-docs/v4/api.yaml
2024-03-11T09:04:36.3781135Z   revision: public/api-docs/v4/api.yaml
2024-03-11T09:04:36.3781925Z   fail-on-diff: true
2024-03-11T09:04:36.3782512Z   include-path-params: false
2024-03-11T09:04:36.3783117Z ##[endgroup]
2024-03-11T09:04:36.4134887Z ##[command]/usr/bin/docker run --name f20768f515724e6648b5a071c71064d81d75_764c82 --label 20f207 --workdir /github/workspace --rm -e "INPUT_BASE" -e "INPUT_REVISION" -e "INPUT_FAIL-ON-DIFF" -e "INPUT_INCLUDE-CHECKS" -e "INPUT_INCLUDE-PATH-PARAMS" -e "INPUT_DEPRECATION-DAYS-BETA" -e "INPUT_DEPRECATION-DAYS-STABLE" -e "HOME" -e "GITHUB_JOB" -e "GITHUB_REF" -e "GITHUB_SHA" -e "GITHUB_REPOSITORY" -e "GITHUB_REPOSITORY_OWNER" -e "GITHUB_REPOSITORY_OWNER_ID" -e "GITHUB_RUN_ID" -e "GITHUB_RUN_NUMBER" -e "GITHUB_RETENTION_DAYS" -e "GITHUB_RUN_ATTEMPT" -e "GITHUB_REPOSITORY_ID" -e "GITHUB_ACTOR_ID" -e "GITHUB_ACTOR" -e "GITHUB_TRIGGERING_ACTOR" -e "GITHUB_WORKFLOW" -e "GITHUB_HEAD_REF" -e "GITHUB_BASE_REF" -e "GITHUB_EVENT_NAME" -e "GITHUB_SERVER_URL" -e "GITHUB_API_URL" -e "GITHUB_GRAPHQL_URL" -e "GITHUB_REF_NAME" -e "GITHUB_REF_PROTECTED" -e "GITHUB_REF_TYPE" -e "GITHUB_WORKFLOW_REF" -e "GITHUB_WORKFLOW_SHA" -e "GITHUB_WORKSPACE" -e "GITHUB_ACTION" -e "GITHUB_EVENT_PATH" -e "GITHUB_ACTION_REPOSITORY" -e "GITHUB_ACTION_REF" -e "GITHUB_PATH" -e "GITHUB_ENV" -e "GITHUB_STEP_SUMMARY" -e "GITHUB_STATE" -e "GITHUB_OUTPUT" -e "RUNNER_OS" -e "RUNNER_ARCH" -e "RUNNER_NAME" -e "RUNNER_ENVIRONMENT" -e "RUNNER_TOOL_CACHE" -e "RUNNER_TEMP" -e "RUNNER_WORKSPACE" -e "ACTIONS_RUNTIME_URL" -e "ACTIONS_RUNTIME_TOKEN" -e "ACTIONS_CACHE_URL" -e "ACTIONS_RESULTS_URL" -e GITHUB_ACTIONS=true -e CI=true -v "/var/run/docker.sock":"/var/run/docker.sock" -v "/home/runner/work/_temp/_github_home":"/github/home" -v "/home/runner/work/_temp/_github_workflow":"/github/workflow" -v "/home/runner/work/_temp/_runner_file_commands":"/github/file_commands" -v "/home/runner/work/<repo>/<repo>":"/github/workspace" 20f207:68f515724e6648b5a071c71064d81d75  "https://<hostname>/api-docs/v4/api.yaml" "public/api-docs/v4/api.yaml" "true" "" "false" "" ""
2024-03-11T09:04:36.8785035Z running oasdiff breaking... base: https://<hostname>/api-docs/v4/api.yaml, revision: public/api-docs/v4/api.yaml, fail_on_diff: true, include_checks: , include_path_params: false, deprecation_days_beta: , deprecation_days_stable: 
2024-03-11T09:04:36.8821578Z flags:  --fail-on WARN
2024-03-11T09:04:40.0841612Z ##[error]in API POST ... the request property '...' became required
<snip>
2024-03-11T09:04:40.1001376Z ##[warning]in API POST ... removed the request property '...'
<snip>
2024-03-11T09:04:40.1080034Z 
2024-03-11T09:04:40.2520210Z Post job cleanup.

Integrate oasdiff action output with github PR

We would like to integrate the output of GitHub Actions, like breaking-changes, with GitHub PRs.
In case there are breaking-changes, the oasdiff output will appear as part of the PR conversation tab.
This would make it easier for our team to collaborate on breaking-changes.

Breaking action does nothing, when fail-on-diff is set to true.

Action is great, annotations are great feature and works well when fail-on-diff is set to false. However when it is set to true, action just fails without adding any addnotation or even returning any log to CI.

I have tested it while base and revision is downloaded from backend, and when base is saved locally in repository. Workaroud is to run action two times, maybe I have something wrong configured, but my configuration is pretty basic.

 - name: Running OpenAPI Spec diff action, this one works fine, but doesn't fail plan
        uses: oasdiff/oasdiff-action/[email protected]
        with:
          base: sample.yml
          revision: http://pathToSwagger
          fail-on-diff: false 

 - name: Running OpenAPI Spec diff action, this fails plan, but doesn't report any issues to user
        uses: oasdiff/oasdiff-action/[email protected]
        with:
          base: sample.yml
          revision: http://pathToSwagger
          fail-on-diff: true

Breaking change detected but action does not fail

I'm using the action oasdiff/oasdiff-action/check-breaking@main to check for breaking changes between two specs.
The action reports a breaking change, but it does not fail. I suspect it is because it is just a "warning" but it actually is a breaking change between the specs, and the action prints a log that says there is 1 breaking change

I also have fail-on-diff: true but it does not fail either.