Skip to content

Commit 4a91cae

Browse files
misterjoshuamisterjoshua
authored
feat: add a maven plugin (#278)
1 parent 7d1cf29 commit 4a91cae

File tree

9 files changed

+261
-0
lines changed

9 files changed

+261
-0
lines changed

‎README.md

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -120,6 +120,35 @@ usage: openapi-diff <old> <new>
120120
--warn Print warning information
121121
```
122122
123+
## Maven Plugin
124+
125+
Add openapi-diff to your POM to show diffs when you test your Maven project. You may opt to throw an error if you have broken backwards compatibility or if your API has changed.
126+
127+
```xml
128+
<plugin>
129+
<groupId>org.openapitools.openapidiff</groupId>
130+
<artifactId>openapi-diff-maven</artifactId>
131+
<version>${openapi-diff-version}</version>
132+
<executions>
133+
<execution>
134+
<goals>
135+
<goal>diff</goal>
136+
</goals>
137+
<configuration>
138+
<!-- Reference specification (perhaps your prod schema) -->
139+
<oldSpec>https://petstore3.swagger.io/api/v3/openapi.json</oldSpec>
140+
<!-- Specification generated by your project in the compile phase -->
141+
<newSpec>${project.basedir}/target/openapi.yaml</newSpec>
142+
<!-- Fail only if API changes broke backward compatibility (default: false) -->
143+
<failOnIncompatible>true</failOnIncompatible>
144+
<!-- Fail if API changed (default: false) -->
145+
<failOnChanged>true</failOnIncompatible>
146+
</configuration>
147+
</execution>
148+
</executions>
149+
</plugin>
150+
```
151+
123152
## Direct Invocation
124153
125154
```java

‎maven/pom.xml

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
<?xml version="1.0"?>
2+
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
3+
<modelVersion>4.0.0</modelVersion>
4+
5+
<parent>
6+
<groupId>org.openapitools.openapidiff</groupId>
7+
<artifactId>openapi-diff-parent</artifactId>
8+
<version>2.0.0-SNAPSHOT</version>
9+
</parent>
10+
11+
<artifactId>openapi-diff-maven</artifactId>
12+
<packaging>jar</packaging>
13+
14+
<name>openapi-diff-maven</name>
15+
<description>Maven plugin for openapi-diff</description>
16+
17+
<dependencies>
18+
<dependency>
19+
<groupId>org.apache.maven</groupId>
20+
<artifactId>maven-plugin-api</artifactId>
21+
<version>3.6.0</version>
22+
<scope>provided</scope>
23+
</dependency>
24+
<dependency>
25+
<groupId>org.apache.maven</groupId>
26+
<artifactId>maven-core</artifactId>
27+
<version>3.6.0</version>
28+
<scope>provided</scope>
29+
</dependency>
30+
<dependency>
31+
<groupId>org.apache.maven.plugin-tools</groupId>
32+
<artifactId>maven-plugin-annotations</artifactId>
33+
<version>3.4</version>
34+
<scope>provided</scope>
35+
</dependency>
36+
37+
<dependency>
38+
<groupId>org.openapitools.openapidiff</groupId>
39+
<artifactId>openapi-diff-core</artifactId>
40+
</dependency>
41+
<dependency>
42+
<groupId>org.junit.jupiter</groupId>
43+
<artifactId>junit-jupiter</artifactId>
44+
<scope>test</scope>
45+
</dependency>
46+
</dependencies>
47+
48+
<build>
49+
<pluginManagement>
50+
<plugins>
51+
<plugin>
52+
<groupId>org.apache.maven.plugins</groupId>
53+
<artifactId>maven-plugin-plugin</artifactId>
54+
<version>3.6.0</version>
55+
</plugin>
56+
<plugin>
57+
<groupId>org.apache.maven.plugins</groupId>
58+
<artifactId>maven-site-plugin</artifactId>
59+
<version>3.8.2</version>
60+
</plugin>
61+
</plugins>
62+
</pluginManagement>
63+
</build>
64+
</project>

‎maven/src/main/java/org/openapitools/openapidiff/maven/ApiChangedException.java

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
package org.openapitools.openapidiff.maven;
2+
3+
import org.apache.maven.plugin.MojoFailureException;
4+
5+
public class ApiChangedException extends MojoFailureException {
6+
public ApiChangedException(String message) {
7+
super(message);
8+
}
9+
}

‎maven/src/main/java/org/openapitools/openapidiff/maven/BackwardIncompatibilityException.java

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
package org.openapitools.openapidiff.maven;
2+
3+
import org.apache.maven.plugin.MojoFailureException;
4+
5+
class BackwardIncompatibilityException extends MojoFailureException {
6+
public BackwardIncompatibilityException(String message) {
7+
super(message);
8+
}
9+
}

‎maven/src/main/java/org/openapitools/openapidiff/maven/OpenApiDiffMojo.java

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
package org.openapitools.openapidiff.maven;
2+
3+
import org.apache.maven.plugin.AbstractMojo;
4+
import org.apache.maven.plugin.MojoExecutionException;
5+
import org.apache.maven.plugin.MojoFailureException;
6+
import org.apache.maven.plugins.annotations.LifecyclePhase;
7+
import org.apache.maven.plugins.annotations.Mojo;
8+
import org.apache.maven.plugins.annotations.Parameter;
9+
import org.openapitools.openapidiff.core.OpenApiCompare;
10+
import org.openapitools.openapidiff.core.model.ChangedOpenApi;
11+
import org.openapitools.openapidiff.core.output.ConsoleRender;
12+
13+
/** A Maven Mojo that diffs two OpenAPI specifications and reports on differences. */
14+
@Mojo(name = "diff", defaultPhase = LifecyclePhase.TEST)
15+
public class OpenApiDiffMojo extends AbstractMojo {
16+
@Parameter(property = "oldSpec")
17+
String oldSpec;
18+
19+
@Parameter(property = "newSpec")
20+
String newSpec;
21+
22+
@Parameter(property = "failOnIncompatible", defaultValue = "false")
23+
Boolean failOnIncompatible = false;
24+
25+
@Parameter(property = "failOnChanged", defaultValue = "false")
26+
Boolean failOnChanged = false;
27+
28+
@Override
29+
public void execute() throws MojoExecutionException, MojoFailureException {
30+
try {
31+
final ChangedOpenApi diff = OpenApiCompare.fromLocations(oldSpec, newSpec);
32+
getLog().info(new ConsoleRender().render(diff));
33+
34+
if (failOnIncompatible && diff.isIncompatible()) {
35+
throw new BackwardIncompatibilityException("The API changes broke backward compatibility");
36+
}
37+
38+
if (failOnChanged && diff.isDifferent()) {
39+
throw new ApiChangedException("The API changed");
40+
}
41+
} catch (RuntimeException e) {
42+
throw new MojoExecutionException("Unexpected error", e);
43+
}
44+
}
45+
}

‎maven/src/test/java/org/openapitools/openapidiff/maven/OpenApiDiffMojoTest.java

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
package org.openapitools.openapidiff.maven;
2+
3+
import static org.junit.jupiter.api.Assertions.*;
4+
5+
import java.io.File;
6+
import org.apache.maven.plugin.MojoExecutionException;
7+
import org.junit.jupiter.api.Test;
8+
9+
class OpenApiDiffMojoTest {
10+
@Test
11+
void Should_NotThrow_When_SpecHasNoChanges() {
12+
final String oldSpec = new File("src/test/resources/oldspec.yaml").getAbsolutePath();
13+
14+
final OpenApiDiffMojo mojo = new OpenApiDiffMojo();
15+
mojo.oldSpec = oldSpec;
16+
mojo.newSpec = oldSpec;
17+
mojo.failOnIncompatible = true;
18+
19+
assertDoesNotThrow(mojo::execute);
20+
}
21+
22+
@Test
23+
void Should_NotThrow_When_SpecIsCompatible() {
24+
final OpenApiDiffMojo mojo = new OpenApiDiffMojo();
25+
mojo.oldSpec = new File("src/test/resources/oldspec.yaml").getAbsolutePath();
26+
mojo.newSpec = new File("src/test/resources/newspec.yaml").getAbsolutePath();
27+
mojo.failOnIncompatible = true;
28+
29+
assertDoesNotThrow(mojo::execute);
30+
}
31+
32+
@Test
33+
void Should_Throw_When_SpecIsDifferent() {
34+
final OpenApiDiffMojo mojo = new OpenApiDiffMojo();
35+
mojo.oldSpec = new File("src/test/resources/oldspec.yaml").getAbsolutePath();
36+
mojo.newSpec = new File("src/test/resources/newspec.yaml").getAbsolutePath();
37+
mojo.failOnChanged = true;
38+
39+
assertThrows(ApiChangedException.class, mojo::execute);
40+
}
41+
42+
@Test
43+
void Should_MojoExecutionException_When_MissingOldSpec() {
44+
final OpenApiDiffMojo mojo = new OpenApiDiffMojo();
45+
mojo.oldSpec = new File("DOES_NOT_EXIST").getAbsolutePath();
46+
mojo.newSpec = new File("src/test/resources/newspec.yaml").getAbsolutePath();
47+
48+
assertThrows(MojoExecutionException.class, mojo::execute);
49+
}
50+
51+
@Test
52+
void Should_MojoExecutionException_When_MissingNewSpec() {
53+
final OpenApiDiffMojo mojo = new OpenApiDiffMojo();
54+
mojo.oldSpec = new File("src/test/resources/oldspec.yaml").getAbsolutePath();
55+
mojo.newSpec = new File("DOES_NOT_EXIST").getAbsolutePath();
56+
57+
assertThrows(MojoExecutionException.class, mojo::execute);
58+
}
59+
60+
@Test
61+
void Should_NotThrow_When_DefaultsAndSpecIsIncompatible() {
62+
final OpenApiDiffMojo mojo = new OpenApiDiffMojo();
63+
mojo.oldSpec = new File("src/test/resources/newspec.yaml").getAbsolutePath();
64+
mojo.newSpec = new File("src/test/resources/oldspec.yaml").getAbsolutePath();
65+
66+
assertDoesNotThrow(mojo::execute);
67+
}
68+
69+
@Test
70+
void Should_BackwardIncompatibilityException_When_WantsExceptionAndSpecIsIncompatible() {
71+
final OpenApiDiffMojo mojo = new OpenApiDiffMojo();
72+
mojo.oldSpec = new File("src/test/resources/newspec.yaml").getAbsolutePath();
73+
mojo.newSpec = new File("src/test/resources/oldspec.yaml").getAbsolutePath();
74+
mojo.failOnIncompatible = true;
75+
76+
assertThrows(BackwardIncompatibilityException.class, mojo::execute);
77+
}
78+
}

‎maven/src/test/resources/newspec.yaml

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
openapi: 3.0.3
3+
info:
4+
title: Generated API
5+
version: "1.0"
6+
paths:
7+
/hello:
8+
get:
9+
responses:
10+
"200":
11+
description: OK
12+
content:
13+
text/plain:
14+
schema:
15+
type: string

‎maven/src/test/resources/oldspec.yaml

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
openapi: 3.0.3
3+
info:
4+
title: Generated API
5+
version: "1.0"
6+
paths: {}

‎pom.xml

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
<modules>
44
<module>core</module>
55
<module>cli</module>
6+
<module>maven</module>
67
</modules>
78

89
<groupId>org.openapitools.openapidiff</groupId>
@@ -31,6 +32,11 @@
3132
<email>jochen@schalanda.name</email>
3233
<url>https://github.com/joschi</url>
3334
</developer>
35+
<developer>
36+
<name>Josh Kellendonk</name>
37+
<email>joshkellendonk@gmail.com</email>
38+
<url>https://github.com/misterjoshua</url>
39+
</developer>
3440
</developers>
3541

3642
<issueManagement>

0 commit comments

Comments
 (0)