Integrating Swagger Brake into Maven/Gradle projects

In the previous article, I’ve covered the general ideas around Swagger Brake and how to use the command-line interface to check your API for breaking changes. Now, I’ll show you how to integrate Swagger Brake into a Maven or a Gradle project.

Integration intro

There are plugins available for both Maven and Gradle projects which makes integration easy. The plugins are using the latest artifact resolution mechanism described in the previous article to retrieve the old version of the API.

There are 2 properties which needs to be provided when configuring the plugins:

• new API path
• Maven repository URL (Nexus/Artifactory)

The same groupId and artifactId will be used for artifact resolution as the project but this can be overridden as well as other properties. By default, the plugins are configured for HTML output and the report will be generated into the project’s build directory under the folder swagger-brake.

Also, if you think about it, when you start a completely new project from scratch, there will be no artifact available in the Maven repository (obviously because it is a new one). For this reason, neither of the plugins will fail execution if the latest artifact cannot be downloaded but a message will be shown that the plugin assumes it is the first time this artifact is getting built.

Swagger Brake Maven plugin

The Maven plugin can be found here. For integrating it into a project, the following configuration needs to be done:

<build>
    <plugins>
        <plugin>
            <groupId>io.redskap</groupId>
            <artifactId>swagger-brake-maven-plugin</artifactId>
            <version>0.1.0</version>
            <executions>
                <execution>
                    <goals>
                        <goal>check</goal>
                    </goals>
                    <configuration>
                        <newApi>${project.build.directory}/generated-sources/swagger/swagger.json</newApi>
                        <mavenRepoUrl>http://localhost:8081/artifactory/libs-snapshot-local</mavenRepoUrl>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

By the time of writing this article, the latest release version of the plugin is 0.1.0. As I’ve already mentioned in the introduction, the 2 parameters needs to be set. The newApi  property needs to point to the swagger file and the mavenRepoUrl  must be an accessible repository URL.

In case the artifact cannot be downloaded, the following message will be shown:

[INFO] Latest version of the artifact could not be retrieved from http://localhost:8081/artifactory/libs-snapshot-local with com.arnoldgalovics.blog:user-service-api
[INFO] Assuming this is the first version of the artifact, skipping check for breaking changes

That’s it for the configuration. Just execute mvn clean package  and the report will be generated under target/swagger-brake/ .

Swagger Brake Gradle plugin

The source for the Gradle plugin can be found here. There are 2 ways you can configure the plugin depending on the Gradle version you are using.

Either through the plugins  block:

plugins {
    id 'io.redskap.swagger-brake'
}

or for older Gradle versions

buildscript {
  repositories {
    mavenCentral()
  }
  dependencies {
    classpath "io.redskap:swagger-brake-gradle:0.1.0"
  }
}
apply plugin: 'io.redskap.swagger-brake'

Now same configuration is needed as for the Maven plugin:

• newApi
• mavenRepoUrl

swaggerBrake {
    mavenRepoUrl = "http://localhost:8081/artifactory/libs-snapshot-local"
    newApi = "${project.buildDir}/src/main/resources/swagger.json"
}

You can start the check by executing gradle clean build . Same message is present in case the latest artifact cannot be retrieved:

> Task :checkBreakingChanges
Latest version of the artifact could not be retrieved from http://localhost:8081/artifactory/libs-snapshot-local with com.arnoldgalovics.blog:user-service-api
Assuming this is the first version of the artifact, skipping check for breaking changes

And that was it for Gradle. Report can be found under build/swagger-brake

Conclusion

That was it for configuring Swagger Brake for Maven and Gradle projects. I’ve also created example Maven and Gradle projects which can be used as reference. Both of them can be found in this GitHub repository.

In case you have any improvement ideas or you just found a bug, let me know by opening an issue on GitHub or just reaching out to me on Twitter.