OpenAPI-diff

Use the openapi-diff-maven plugin to integrate API compatibility checks into your Maven build lifecycle. You can configure it to fail the build if backward compatibility is broken or if any changes are detected.

<plugin>
  <groupId>org.openapitools.openapidiff</groupId>
  <artifactId>openapi-diff-maven</artifactId>
  <version>${openapi-diff-version}</version>
  <executions>
    <execution>
      <goals>
        <goal>diff</goal>
      </goals>
      <configuration>
        <!-- Reference specification (perhaps your prod schema) -->
        <oldSpec>https://petstore3.swagger.io/api/v3/openapi.json</oldSpec>
        <!-- Specification generated by your project in the compile phase -->
        <newSpec>${project.basedir}/target/openapi.yaml</newSpec>
        <!-- Fail only if API changes broke backward compatibility (default: false) -->
        <failOnIncompatible>true</failOnIncompatible>
        <!-- Fail if API changed (default: false) -->
        <failOnChanged>true</failOnChanged>
        <!-- Supply file path for console output to file if desired. -->
        <consoleOutputFileName>${project.basedir}/../maven/target/diff.txt</consoleOutputFileName>
        <!-- Supply json output to file if desired. -->
        <jsonOutputFileName>${project.basedir}/../maven/target/diff.json</jsonOutputFileName>
        <!-- Supply markdown output to file if desired. -->
        <markdownOutputFileName>${project.basedir}/../maven/target/diff.md</markdownOutputFileName>
        <!-- Supply config file(s), e.g. to disable incompatibility checks. Later files override earlier files -->
        <configFiles>
          <configFile>my/config-file.yaml</configFile>
        </configFiles>
        <!-- Supply config properties, e.g. to disable incompatibility checks. Overrides configFiles. -->
        <configProps>
          <incompatible.response.enum.increased>false</incompatible.response.enum.increased>
        </configProps>
      </configuration>
    </execution>
  </executions>
</plugin>

The openapi-diff command-line tool compares two OpenAPI specifications (the old and the new versions) and identifies changes, including backward compatibility breaks.

Basic Usage:

openapi-diff <old_spec_path> <new_spec_path>

Arguments:

• <old>: Path or URL to the original OpenAPI specification.
• <new>: Path or URL to the updated OpenAPI specification.

Exit Codes:

• 0: Success (no incompatible changes if --fail-on-incompatible is used, or if the spec is unchanged if --fail-on-changed is used).
• 1: Failure (incompatible changes detected when using --fail-on-incompatible, or changes detected when using --fail-on-changed).
• 2: Error (parsing failure or unexpected exception).

# Example: Compare two local files and output a JSON diff
openapi-diff old_spec.yaml new_spec.yaml --json diff_output.json

# Example: Compare and fail if backward compatibility is broken
openapi-diff old_spec.yaml new_spec.yaml --fail-on-incompatible

# Example: Only output the diff state (no_changes, incompatible, compatible)
openapi-diff old_spec.yaml new_spec.yaml --state

You can use the OpenApiCompare class to perform comparisons programmatically.

Basic Comparison:

ChangedOpenApi diff = OpenApiCompare.fromLocations(oldSpecPath, newSpecPath);

Custom Path Matching: By default, the DefaultPathMatcher obfuscates path parameter names (e.g., /users/{id} matches /users/{userId}). To use a custom matching strategy, implement the PathMatcher interface and provide it via OpenApiDiffOptions:

OpenApiDiffOptions options = OpenApiDiffOptions
    .builder()
    .pathMatcher(new MyCustomPathMatcher())
    .build();

ChangedOpenApi diff = OpenApiCompare.fromLocations(oldSpec, newSpec, null, options);

public class Main {
    public static final String OPENAPI_DOC1 = "petstore_v3_1.json";
    public static final String OPENAPI_DOC2 = "petstore_v2_2.yaml";
        
    public static void main(String[] args) {
        ChangedOpenApi diff = OpenApiCompare.fromLocations(OPENAPI_DOC1, OPENAPI_DOC2);
    }
}

When consuming the JSON output programmatically, the following top-level keys are available to assess the differences between two OpenAPI specifications:

• compatible: Boolean indicating if the changes are backward compatible.
• incompatible: Boolean indicating if breaking changes were detected.
• different: Boolean indicating if any differences exist.
• newEndpoints: An array of objects representing newly added endpoints (includes method, pathUrl, summary, and the full operation object).
• missingEndpoints: An array of endpoints present in the old spec but missing in the new one.
• changedOperations: An array of operations that have undergone modifications.
• deprecatedEndpoints: An array of endpoints that have been marked as deprecated.
• changedElements: Details on specific element changes.
• oldSpecOpenApi: The original OpenAPI specification object.
• newSpecOpenApi: The updated OpenAPI specification object.

{
    "changedElements": [...],
    "changedExtensions": null,
    "changedOperations": [...],
    "compatible": false,
    "deprecatedEndpoints": [...],
    "different": true,
    "incompatible": true,
    "missingEndpoints": [...],
    "newEndpoints": [
        {
            "method": "GET",
            "operation": {
                "operationId": "getPetById",
                "summary": "Find pet by ID",
                "pathUrl": "/pet/{petId}",
                "parameters": [...]
            }
        }
    ],
    "newSpecOpenApi": {...},
    "oldSpecOpenApi": {...},
    "unchanged": false
}

The CLI tool compares two OpenAPI 3.x specifications (provided as file paths or HTTP URLs) and outputs the differences.

Basic Syntax: openapi-diff <old> <new> [options]

Key Options:

• --html <file>: Export diff as HTML to the specified file.
• --json <file>: Export diff as JSON to the specified file.
• --markdown <file>: Export diff as Markdown to the specified file.
• --asciidoc <file>: Export diff as Asciidoc to the specified file.
• --text <file>: Export diff as plain text to the specified file.
• --fail-on-incompatible: Fail if API changes broke backward compatibility.
• --fail-on-changed: Fail if API changed but remains backward compatible.
• --state <state>: Only output diff state: no_changes, incompatible, or compatible.
• --config-file <file>: Use a .yaml config file to override default behavior.
• --config-prop <key:value>: Override a specific configuration property (e.g., my.prop:true).

$ openapi-diff --help