OpenAPI Diff Tool Gradle Plugin

Introduction

The OpenAPITools Diff Tool is useful in comparing 2 specifications. As part of the original repository a maven plugin is included but for those of us that prefer Gradle there was no plugin to be found. This repository contains the code to implement such a plugin.

The plugin has been implemented with an Extension, allowing for the configuration options to be passed in a block assigned with "openapi_diff", and can be used in the build.gradle file

plugins {
    id 'com.x3t.gradle.plugins.openapi.openapi_diff'
}

openapi_diff {
    originalFile = "old_specification.yaml"
    newFile = "new_specification.yaml"
}

The functionality can also be used by creating a task in the build.gradle similar to

plugins {
    id 'com.x3t.gradle.plugins.openapi.openapi_diff'
}

task triggerCompatible(type: com.x3t.gradle.plugins.openapi.OpenapiDiffPluginTask){
    originalFile = "old_specification.yaml"
    newFile = "new_specification.yaml"
}

Options

Property name	Type	Default Value	Required	Description
originalFile	Property<String>	""	Yes	Filename for the original version of the specification.
newFile	Property<String>	""	Yes	Filename for the original version of the specification.
failOnChange	Property<Boolean>	false	No	Set to true if you wish for the build to fail on any changes.
failOnIncompatible	Property<Boolean>	false	No	Set to true if you wish for the build to fail on incompatible changes.
htmlReport	Property<Boolean>	false	No	Enable to create a comparison report in HTML format.
jsonReport	Property<Boolean>	false	No	Enable to create a comparison report in JSON format.
textReport	Property<Boolean>	false	No	Enable to create a comparison report Plaintext format.
markdownReport	Property<Boolean>	false	No	Enable to create a comparison report Markdown format.
asciidocReport	Property<Boolean>	false	No	Enable to create a comparison report Asciidoc format.
reportName	Property<String>	"build/Openapi_Diff_Report"	No	The location and name to use for any report file.

Note	The reportName property is used in the creation of the report files.

If this is left as default then the reports will be named

"build/Openapi_Diff_Report.txt"

"build/Openapi_Diff_Report.json"

"build/Openapi_Diff_Report.md"

"build/Openapi_Diff_Report.html"

"build/Openapi_Diff_Report.adoc"

depending on which options are enabled.

Building & Testing

Build

To build the plugin you can use the standard Gradle commands of

./gradlew jar

To publish to your local maven repository

./gradlew publish

If the version is set with "-SNAPSHOT" it will automatically publish locally to a sub-directory called repo.

Local Testing

To perform testing local you can run the Gradle build in the demo sub-directory. This will use the ./repo directory to source the plugin for testing.

Another way to test the plugin is to run the following from the root directory.

./gradlew test functionalTest

This will run JUnit tests and will trigger TestKit tests with the functionalTest task.

Publish Plugin

To publish the plugin you need to

1. Ensure the API key and secret, for x3tadmin, have been added to ~/.gradle/gradle.properties

2. The version string has been updated to remove "-SNAPSHOT" and is greater than the last published version.

You then need to open a terminal and run

./gradlew publishPlugins