Skip to content

Commit

Permalink
#95: Report changes optionally
Browse files Browse the repository at this point in the history
  • Loading branch information
@galovics
galovics committed May 14, 2024
1 parent 17783b4 commit c7b327e
Show file tree
Hide file tree
Showing 20 changed files with 314 additions and 87 deletions.
6 changes: 0 additions & 6 deletions build.gradle
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,8 +47,6 @@ subprojects {
implementation "org.springframework:spring-context:6.0.13"
implementation "com.fasterxml.jackson.dataformat:jackson-dataformat-xml:2.13.4"

testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine:5.10.0'
testImplementation 'org.junit.jupiter:junit-jupiter-api:5.10.0'
testImplementation "org.assertj:assertj-core:3.24.2"
testImplementation "org.springframework:spring-test:6.0.13"
testImplementation "org.mockito:mockito-core:5.6.0"
Expand All @@ -71,10 +69,6 @@ subprojects {
showProgress = false
}

test {
useJUnitPlatform()
}

//<editor-fold desc="Uploading to central">
apply plugin: 'signing'

Expand Down
16 changes: 15 additions & 1 deletion src-docs/src/cli/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -118,6 +118,19 @@ Example command:
$ java -jar swagger-brake.jar --old-api=swagger.yaml --new-api=swagger2.yaml --excluded-paths=/auth
```

## Ignoring specific breaking changes
For detailed description on the feature, see [Ignoring specific breaking changes](../configuration/README.md#ignoring-specific-breaking-changes).

There's a parameter `--ignored-breaking-change-rules` where you can provide a list of rule codes you want to be ignored
during the check. The rules can be separated by commas. The rule codes can be found in the docs.

Example command:

```bash
$ java -jar swagger-brake.jar --old-api=swagger.yaml --new-api=swagger2.yaml --ignored-breaking-change-rules=R001,R002
```


## Full list of parameters
| <div style="width:250px">Parameter</div> | Description |
|:------------------------------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------------:|
Expand All @@ -135,4 +148,5 @@ $ java -jar swagger-brake.jar --old-api=swagger.yaml --new-api=swagger2.yaml --e
| `--artifact-packaging` | Specifies the artifact packaging. Could be jar or war. Used when resolving the latest artifact version. Defaults to jar if not specified. |
| `--api-filename` | The filename to search for within the artifact. |
| `--beta-api-extension-name` | The name of the custom vendor extension attribute that denotes beta APIs. |
| `--excluded-paths` | A comma separated list of path prefixes that shall be excluded from the scan.
| `--excluded-paths` | A comma separated list of path prefixes that shall be excluded from the scan.
| `--ignored-breaking-change-rules` | Specifies which breaking changes shall be ignored. Rules have to be provided (find them in the doc). Multiple values can be provided by using comma. Example: R001,R002
12 changes: 11 additions & 1 deletion src-docs/src/configuration/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -218,4 +218,14 @@ CLI configuration [here](../cli/README.md#excluding-paths-from-the-scan).

Maven configuration [here](../maven/README.md#excluding-paths-from-the-scan).

Gradle configuration [here](../gradle/README.md#excluding-paths-from-the-scan).
Gradle configuration [here](../gradle/README.md#excluding-paths-from-the-scan).

## Ignoring specific breaking changes
In case you don't want a specific rule to be considered as a breaking change for your API, you can disable them.


CLI configuration [here](../cli/README.md#ignoring-specific-breaking-changes).

Maven configuration [here](../maven/README.md#ignoring-specific-breaking-changes).

Gradle configuration [here](../gradle/README.md#ignoring-specific-breaking-changes).
20 changes: 19 additions & 1 deletion src-docs/src/gradle/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -166,6 +166,23 @@ swaggerBrake {
...
```


## Ignoring specific breaking changes
For detailed description on the feature, see [Ignoring specific breaking changes](../configuration/README.md#ignoring-specific-breaking-changes).

Similarly, to other configurations, use the `ignoredBreakingChangeRules` parameter.

Example:
```groovy
...
swaggerBrake {
newApi = "${project.buildDir}/resources/main/swagger.yaml"
mavenRepoUrl = "${REPO_URL}/artifactory/libs-release-local"
ignoredBreakingChangeRules = ['R001', 'R002']
}
...
```

## Default parameter values

| Parameter | Default value |
Expand Down Expand Up @@ -194,4 +211,5 @@ swaggerBrake {
| `artifactPackaging` | Specifies the artifact packaging. Could be jar or war. Defaults to jar. If the Gradle War plugin is applied, war is used. |
| `apiFilename` | The filename to search for within the artifact. |
| `betaApiExtensionName` | The name of the custom vendor extension attribute that denotes beta APIs. |
| `excludedPaths` | A list of path prefixes that shall be excluded from the scan. |
| `excludedPaths` | A list of path prefixes that shall be excluded from the scan. |
| `ignoredBreakingChangeRules` | A list of rule codes that shall be ignored during the scan. |
73 changes: 56 additions & 17 deletions src-docs/src/maven/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -263,6 +263,44 @@ Example:
...
```


## Ignoring specific breaking changes
For detailed description on the feature, see [Ignoring specific breaking changes](../configuration/README.md#ignoring-specific-breaking-changes).

Similarly, to other configurations, use the `<ignoredBreakingChangeRules>` parameter.

Example:
```xml
...
<build>
<plugins>
...
<plugin>
<groupId>io.redskap</groupId>
<artifactId>swagger-brake-maven-plugin</artifactId>
<version>2.4.0</version>
<executions>
<execution>
<goals>
<goal>check</goal>
</goals>
<configuration>
<newApi>${project.build.directory}/generated-sources/swagger/swagger.json</newApi>
<mavenRepoUrl>http://${REPO_URL}/artifactory/libs-release-local</mavenRepoUrl>
<ignoredBreakingChangeRules>
<ignoredBreakingChangeRule>R001</ignoredBreakingChangeRule>
<ignoredBreakingChangeRule>R002</ignoredBreakingChangeRule>
</ignoredBreakingChangeRules>
</configuration>
</execution>
</executions>
</plugin>
...
</plugins>
</build>
...
```

## Default parameter values

| Parameter | Default value |
Expand All @@ -275,20 +313,21 @@ Example:
| `<artifactPackaging>` | `${project.packaging}` |

## Full list of parameters
| Parameter | Description |
|:--------------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------------:|
| `<oldApi>` | Denotes the path of the baseline API. Can be a relative path and an absolute one. |
| `<newApi>` | Denotes the path of the new, changed API. Can be a relative path and an absolute one. |
| `<outputFormats>` | Specifies which reports shall be generated. Possible values: `STDOUT`, `JSON`, `HTML` |
| `<outputFilePath>` | Denotes the folder where the file reports shall be saved. Can be a relative path and an absolute one. In case the path doesn't exist, it will be created. |
| `<mavenRepoUrl>` | Specifies the release repository base URL. Might be optional in case `<mavenSnapshotRepoUrl>` is provided. |
| `<mavenSnapshotRepoUrl>` | Specifies the snapshot repository base URL. Might be optional in case `<mavenRepoUrl>` is provided. |
| `<mavenRepoUsername>` | The username for the Maven repository. |
| `<mavenRepoPassword>` | The password for the Maven repository. |
| `<groupId>` | The groupId of the artifact. |
| `<artifactId>` | The artifactId of the artifact. |
| `<currentArtifactVersion>` | The version of the artifact that contains the new API. This is used to determine if the snapshot, or the release repository needs to be used. |
| `<artifactPackaging>` | Specifies the artifact packaging. Could be jar or war. Defaults to jar. If the `<packaging>` property is set on the project, it'll be used. |
| `<apiFilename>` | The filename to search for within the artifact. |
| `<betaApiExtensionName>` | The name of the custom vendor extension attribute that denotes beta APIs. |
| `<excludedPaths>` | A list of path prefixes that shall be excluded from the scan. |
| Parameter | Description |
|:------------------------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------------:|
| `<oldApi>` | Denotes the path of the baseline API. Can be a relative path and an absolute one. |
| `<newApi>` | Denotes the path of the new, changed API. Can be a relative path and an absolute one. |
| `<outputFormats>` | Specifies which reports shall be generated. Possible values: `STDOUT`, `JSON`, `HTML` |
| `<outputFilePath>` | Denotes the folder where the file reports shall be saved. Can be a relative path and an absolute one. In case the path doesn't exist, it will be created. |
| `<mavenRepoUrl>` | Specifies the release repository base URL. Might be optional in case `<mavenSnapshotRepoUrl>` is provided. |
| `<mavenSnapshotRepoUrl>` | Specifies the snapshot repository base URL. Might be optional in case `<mavenRepoUrl>` is provided. |
| `<mavenRepoUsername>` | The username for the Maven repository. |
| `<mavenRepoPassword>` | The password for the Maven repository. |
| `<groupId>` | The groupId of the artifact. |
| `<artifactId>` | The artifactId of the artifact. |
| `<currentArtifactVersion>` | The version of the artifact that contains the new API. This is used to determine if the snapshot, or the release repository needs to be used. |
| `<artifactPackaging>` | Specifies the artifact packaging. Could be jar or war. Defaults to jar. If the `<packaging>` property is set on the project, it'll be used. |
| `<apiFilename>` | The filename to search for within the artifact. |
| `<betaApiExtensionName>` | The name of the custom vendor extension attribute that denotes beta APIs. |
| `<excludedPaths>` | A list of path prefixes that shall be excluded from the scan. |
| `<ignoredBreakingChangeRules>` | A list of rule codes that shall be ignored during the scan. |
11 changes: 11 additions & 0 deletions swagger-brake-cli/build.gradle
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,8 @@ dependencies {
implementation project(":swagger-brake")
implementation "ch.qos.logback:logback-core:1.2.11"
implementation "ch.qos.logback:logback-classic:1.2.11"
testImplementation 'org.junit.jupiter:junit-jupiter:5.10.0'
testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
}

jar {
Expand All @@ -31,4 +33,13 @@ jar {
shadowJar {
archiveBaseName = 'swagger-brake'
archiveClassifier = 'cli'
}


tasks.named('test', Test) {
useJUnitPlatform()

testLogging {
events "passed"
}
}
3 changes: 2 additions & 1 deletion swagger-brake-cli/src/main/java/io/redskap/swagger/brake/cli/options/CliOption.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,8 @@ public enum CliOption {

API_FILENAME("api-filename"),
BETA_API_EXTENSION_NAME("beta-api-extension-name"),
EXCLUDED_PATHS("excluded-paths");
EXCLUDED_PATHS("excluded-paths"),
IGNORED_BREAKING_CHANGE_RULES("ignored-breaking-change-rules");


private final String cliOptionName;
Expand Down
35 changes: 35 additions & 0 deletions ...io/redskap/swagger/brake/cli/options/handler/IgnoredBreakingChangeRulesOptionHandler.java
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
package io.redskap.swagger.brake.cli.options.handler;

import static java.util.stream.Collectors.toSet;

import io.redskap.swagger.brake.cli.options.CliOption;
import io.redskap.swagger.brake.runner.Options;
import java.util.Arrays;
import lombok.extern.slf4j.Slf4j;
import org.apache.commons.lang3.StringUtils;
import org.springframework.stereotype.Component;

@Component
@Slf4j
public class IgnoredBreakingChangeRulesOptionHandler implements CliOptionHandler {
@Override
public void handle(String optionValue, Options options) {
if (StringUtils.isNotBlank(optionValue)) {
log.debug("Handling {} parameter with value {}", getHandledCliOption(), optionValue);
String[] ignoredBreakingChangeRules = optionValue.split(",");
log.debug("Splitted values are {}", ignoredBreakingChangeRules);
options.setIgnoredBreakingChangeRules(Arrays.stream(ignoredBreakingChangeRules).map(String::trim).collect(toSet()));
}

}

@Override
public CliOption getHandledCliOption() {
return CliOption.IGNORED_BREAKING_CHANGE_RULES;
}

@Override
public String getHelpMessage() {
return "Specifies which breaking changes shall be ignored. Rules have to be provided (find them in the doc). Multiple values can be provided by using comma. Example: R001,R002";
}
}
12 changes: 11 additions & 1 deletion swagger-brake/build.gradle
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,21 @@ repositories {
mavenCentral()
}


dependencies {
implementation "org.apache.commons:commons-collections4:4.4"
implementation "io.swagger.parser.v3:swagger-parser:2.0.5"
implementation "com.fasterxml.jackson.core:jackson-databind:2.13.4.2"
implementation "com.github.spullara.mustache.java:compiler:0.9.11"
implementation "org.apache.httpcomponents:httpclient:4.5.14"

testImplementation 'org.junit.jupiter:junit-jupiter:5.10.0'
testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
}

tasks.named('test', Test) {
useJUnitPlatform()

testLogging {
events "passed"
}
}
6 changes: 3 additions & 3 deletions swagger-brake/src/main/java/io/redskap/swagger/brake/report/AbstractFileReporter.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,12 +19,12 @@ public abstract class AbstractFileReporter implements Reporter {
private final DirectoryCreator directoryCreator;

@Override
public void report(Collection<BreakingChange> breakingChanges, Options options, ApiInfo apiInfo) {
public void report(Collection<BreakingChange> breakingChanges, Collection<BreakingChange> ignoredBreakingChanges, Options options, ApiInfo apiInfo) {
if (StringUtils.isBlank(options.getOutputFilePath())) {
log.warn("No file reporting has been done since output file path is not set");
return;
}
String json = toFileContent(breakingChanges, apiInfo);
String json = toFileContent(breakingChanges, ignoredBreakingChanges, apiInfo);
try {
directoryCreator.create(options.getOutputFilePath());
String filePath = options.getOutputFilePath() + File.separator + getFilename(apiInfo);
Expand All @@ -37,5 +37,5 @@ public void report(Collection<BreakingChange> breakingChanges, Options options,

protected abstract String getFilename(ApiInfo apiInfo);

protected abstract String toFileContent(Collection<BreakingChange> breakingChanges, ApiInfo apiInfo);
protected abstract String toFileContent(Collection<BreakingChange> breakingChanges, Collection<BreakingChange> ignoredBreakingChanges, ApiInfo apiInfo);
}
5 changes: 5 additions & 0 deletions swagger-brake/src/main/java/io/redskap/swagger/brake/report/CompositeReporter.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,4 +20,9 @@ public void report(Collection<BreakingChange> breakingChanges, Options options)
public void report(Collection<BreakingChange> breakingChanges, Options options, ApiInfo apiInfo) {
delegates.forEach(d -> d.report(breakingChanges, options, apiInfo));
}

@Override
public void report(Collection<BreakingChange> breakingChanges, Collection<BreakingChange> ignoredBreakingChanges, Options options, ApiInfo apiInfo) {
delegates.forEach(d -> d.report(breakingChanges, ignoredBreakingChanges, options, apiInfo));
}
}
6 changes: 5 additions & 1 deletion swagger-brake/src/main/java/io/redskap/swagger/brake/report/HtmlReporter.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,13 +44,17 @@ protected String getFilename(ApiInfo apiInfo) {
}

@Override
protected String toFileContent(Collection<BreakingChange> breakingChanges, ApiInfo apiInfo) {
protected String toFileContent(Collection<BreakingChange> breakingChanges, Collection<BreakingChange> ignoredBreakingChanges, ApiInfo apiInfo) {
String mustacheTemplate = "htmlreporter/swagger-brake.mustache";
HtmlData data = new HtmlData();
List<BreakingChangeTableRow> tableRows = breakingChanges.stream().map(BreakingChangeTableRow::new).collect(Collectors.toCollection(ArrayList::new));
if (!tableRows.isEmpty()) {
data.setBreakingChanges(tableRows);
}
List<BreakingChangeTableRow> ignoredTableRows = ignoredBreakingChanges.stream().map(BreakingChangeTableRow::new).collect(Collectors.toCollection(ArrayList::new));
if (!ignoredBreakingChanges.isEmpty()) {
data.setIgnoredBreakingChanges(ignoredTableRows);
}

Map<String, Map<String, Object>> paramMap = new HashMap<>();
paramMap.put("data", jsonConverter.toMap(data));
Expand Down
Loading

0 comments on commit c7b327e

Please sign in to comment.