Validating swagger/openapi json using openapi-validations GitHub Action

Validating swagger/openapi json using openapi-validations GitHub Action
Photo by Maël BALLAND / Unsplash

A few months back I had a requirement of checking the APIs for the product I'm working on for breaking changes (Backward Compatibility Check) during CI/CD. As part of that research, I created an action called openapi-validations, which is essentially a wrapper on top of the following 2 prominent NPM packages:

  • swagger-parser - Swagger 2.0 and OpenAPI 3.0 parser/validator
  • openapi-diff - A CLI tool to identify differences between Swagger or OpenAPI specifications

While building openapi-validations action I had only 1 pre-requisite that it should support both Swagger2 and OpenAPI3 (next increment of swagger2).

This article essentially is a how-to-guide to use this action in your CI/CD effectively. So let's begin.

What openapi-validations action can do?

There are 2 primary objectives for this action.

1) Validate provided 2 swagger jsons for validation errors (always performed)
2) Verify any breaking changes between the 2 swagger specifications (can be skipped)

Additionally, this action can be configured to have a blocking_decision, which can be configured to either mark the whole run as failed or not

Creating a Simple Test workflow based on openapi-validations

I've created this simple action workflow to demonstrate how to use it in your workflows.

The pre-requisites for this workflow are:

1) source.json file, (Source File) which is the one that one would want to test for breaking changes
2) A destination.json file (Benchmark file) which is the one that one would want to compare against for breaking changes

name: try-this-action
          required: true
          type: string
          description: 'Source File Name: (source.json)'
          required: false
          type: string
          description: 'Benchmark file name: (destination.json)'
          required: true
          type: choice
            - all
            - schema-validation-only
          description: 'type of validations to run [all, schema-validation-only]'
          required: true
          type: choice
            - none
            - strict
          description: 'action if failed [strict, none (default)]'
    runs-on: ubuntu-latest
    name: swagger-validator
      - name: run swagger validations
        id: step1
        uses: far11ven/[email protected]
          source_file:   ${{ github.event.inputs.source_file }}
          benchmark_file:  ${{ github.event.inputs.benchmark_file }}
          blocking_decision:  ${{ github.event.inputs.on_failure_decision }}
          validations: ${{ github.event.inputs.validations }}
      # Use the output from the step1
      - name: list the results
        id: step2
        run: |
          echo "The Errors found in Swagger schema: ${{ steps.step1.outputs.swagger_validation_results }}"
          echo "The Diffs found in Swagger schema comparison ${{ steps.step1.outputs.openapi_diff_results }}"


Depending upon whether you set blocking_decision to 'strict' your workflow will list out all the breaking changes and will validate the swagger schema as per either swagger2 or OpenAPI3 specification

What are considered breaking changes by this workflow?

  • Breaking Changes:
  1. Response Code changed
  2. Response ContentType Changed
  3. Response Field Type changed (for ex array to String etc)
  4. Endpoint path removed
  5. Request Method changed
  •  Non-Breaking Changes:
  1. ParamType changed (Path, Query, etc)
  2. RequestBody ContentType Changed
  3. RequestBody fieldType Changed
  4. RequestBody field required status changed etc

Sample results:

You can select the relevant fields in the action run workflow option:

Swagger Validation Error with blocking_decision 'strict':

Breaking changes with blocking_decision 'strict':

NOTE: Currently this action does not have support for yaml swagger schema.