Dec 20, 2023 3 min read github-actions

Validating swagger/openapi json using openapi-validations GitHub Action

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
on:
    workflow_dispatch:
      inputs:
        source_file:
          required: true
          type: string
          description: 'Source File Name: (source.json)'
        benchmark_file:
          required: false
          type: string
          description: 'Benchmark file name: (destination.json)'
        validations:
          required: true
          type: choice
          options:
            - all
            - schema-validation-only
          description: 'type of validations to run [all, schema-validation-only]'
        on_failure_decision:
          required: true
          type: choice
          options:
            - none
            - strict
          description: 'action if failed [strict, none (default)]'
jobs:
  validation_job:
    runs-on: ubuntu-latest
    name: swagger-validator
    steps:
      - name: run swagger validations
        id: step1
        uses: far11ven/[email protected]
        with:
          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 }}"

try-this-action.yaml

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