Requirements

Feature

Maven

<dependency>  <groupId>org.openapitools.openapidiff</groupId>  <artifactId>openapi-diff-core</artifactId>  <version>${openapi-diff-version}</version></dependency>

Homebrew

brew install openapi-diff

Docker

# docker run openapitools/openapi-diff:latestusage: openapi-diff<old><new>    --asciidoc<file>export diff as asciidocin given file    --debug                     Print debugging information    --error                     Print error information    --fail-on-changed           Failif API changed but is backward                                compatible    --fail-on-incompatible      Fail onlyif API changes broke backward                                compatibility    --config-file               Config file to override default behavior. Supported file formats: .yaml    --config-prop               Config property to override default behavior with key:value format (e.g. my.prop:true) -h,--help                      print this message    --header<property=value>   use given headerfor authorisation    --html<file>export diff as htmlin given file    --info                      Print additional information    --json<file>export diff as jsonin given file -l,--log<level>               use given levelfor log (TRACE, DEBUG,                                INFO, WARN, ERROR, OFF). Default: ERROR    --markdown<file>export diff as markdownin given file    --off                       No information printed    --query<property=value>    use query paramfor authorisation    --state                     Only output diff state: no_changes,                                incompatible, compatible    --text<file>export diff as textin given file    --trace                     be extra verbose    --version                   print the version information andexit    --warn                      Print warning information

Build the image

docker build -t local-openapi-diff.

Run an instance

docker run --rm -t \  -v$(pwd)/core/src/test/resources:/specs:ro \  openapitools/openapi-diff:latest /specs/path_1.yaml /specs/path_2.yaml

Usage

Command Line

$ openapi-diff --helpusage: openapi-diff<old><new>    --asciidoc<file>export diff as asciidocin given file    --debug                     Print debugging information    --error                     Print error information -h,--help                      print this message    --header<property=value>   use given headerfor authorisation    --html<file>export diff as htmlin given file    --info                      Print additional information    --json<file>export diff as jsonin given file -l,--log<level>               use given levelfor log (TRACE, DEBUG,                                INFO, WARN, ERROR, OFF). Default: ERROR    --markdown<file>export diff as markdownin given file    --off                       No information printed    --query<property=value>    use query paramfor authorisation    --state                     Only output diff state: no_changes,                                incompatible, compatible    --fail-on-incompatible      Fail onlyif API changes broke backward compatibility    --fail-on-changed           Failif API changed but is backward compatible    --config-file               Config file to override default behavior. Supported file formats: .yaml    --config-prop               Config property to override default behavior with key:value format (e.g. my.prop:true)    --trace                     be extra verbose    --version                   print the version information andexit    --warn                      Print warning information

Maven Plugin

<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 file path for json output to file if desired.-->        <jsonOutputFileName>${project.basedir}/../maven/target/diff.json</jsonOutputFileName><!-- Supply file path for 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>

Direct Invocation

publicclassMain {publicstaticfinalStringOPENAPI_DOC1 ="petstore_v3_1.json";publicstaticfinalStringOPENAPI_DOC2 ="petstore_v2_2.yaml";publicstaticvoidmain(String[]args) {ChangedOpenApidiff =OpenApiCompare.fromLocations(OPENAPI_DOC1,OPENAPI_DOC2);//...    }}

Path Matching while comparing two OpenAPI paths

OpenApiDiffOptionsoptions =OpenApiDiffOptions    .builder()    .pathMatcher(newMyCustomPathMatcher())    .build();ChangedOpenApidiff =OpenApiCompare.fromLocations(oldSpec,newSpec,null,options);

Render difference

HTML

HtmlRenderhtmlRender =newHtmlRender("Changelog","http://deepoove.com/swagger-diff/stylesheets/demo.css");FileOutputStreamoutputStream =newFileOutputStream("testDiff.html");OutputStreamWriteroutputStreamWriter =newOutputStreamWriter(outputStream);htmlRender.render(diff,outputStreamWriter);

Markdown

MarkdownRendermarkdownRender =newMarkdownRender();FileOutputStreamoutputStream =newFileOutputStream("testDiff.md");OutputStreamWriteroutputStreamWriter =newOutputStreamWriter(outputStream);markdownRender.render(diff,outputStreamWriter);

Asciidoc

AsciidocRenderasciidocRender =newAsciidocRender();FileOutputStreamoutputStream =newFileOutputStream("testDiff.adoc");OutputStreamWriteroutputStreamWriter =newOutputStreamWriter(outputStream);asciidocRender.render(diff,outputStreamWriter);

JSON

JsonRenderjsonRender =newJsonRender();FileOutputStreamoutputStream =newFileOutputStream("testDiff.json");OutputStreamWriteroutputStreamWriter =newOutputStreamWriter(outputStream);jsonRender.render(diff,outputStreamWriter);

Extensions

Examples

CLI Output

============================================================================                            API CHANGE LOG                            ============================================================================                             Swagger Petstore                             ----------------------------------------------------------------------------                              What's New                              ----------------------------------------------------------------------------- GET    /pet/{petId}----------------------------------------------------------------------------                            What's Deleted                            ----------------------------------------------------------------------------- POST   /pet/{petId}----------------------------------------------------------------------------                          What's Deprecated                           ----------------------------------------------------------------------------- GET    /user/logout----------------------------------------------------------------------------                            What's Changed                            ----------------------------------------------------------------------------- PUT    /pet  Request:        - Deleted application/xml        - Changed application/json          Schema: Backward compatible- POST   /pet  Parameter:    - Add tags in query  Request:        - Changed application/xml          Schema: Backward compatible        - Changed application/json          Schema: Backward compatible- GET    /pet/findByStatus  Parameter:    - Deprecated status in query  Return Type:    - Changed 200 OK      Media types:        - Changed application/xml          Schema: Broken compatibility        - Changed application/json          Schema: Broken compatibility- GET    /pet/findByTags  Return Type:    - Changed 200 OK      Media types:        - Changed application/xml          Schema: Broken compatibility        - Changed application/json          Schema: Broken compatibility- DELETE /pet/{petId}  Parameter:    - Add newHeaderParam in header- POST   /pet/{petId}/uploadImage  Parameter:    - Changed petId in path- POST   /user  Request:        - Changed application/json          Schema: Backward compatible- POST   /user/createWithArray  Request:        - Changed application/json          Schema: Backward compatible- POST   /user/createWithList  Request:        - Changed application/json          Schema: Backward compatible- GET    /user/login  Parameter:    - Delete password in query- GET    /user/logout- GET    /user/{username}  Return Type:    - Changed 200 OK      Media types:        - Changed application/xml          Schema: Broken compatibility        - Changed application/json          Schema: Broken compatibility- PUT    /user/{username}  Request:        - Changed application/json          Schema: Backward compatible----------------------------------------------------------------------------                                Result                                ----------------------------------------------------------------------------                 API changes broke backward compatibility                 --------------------------------------------------------------------------

Markdown

###What's New---*`GET` /pet/{petId} Find pet by ID###What's Deleted---*`POST` /pet/{petId} Updates a pet in the store with form data###What's Deprecated---*`GET` /user/logout Logs out current logged in user session###What's Changed---*`PUT` /pet Update an existing pet      Request  Deleted request body : [application/xml]  Changed response : [application/json]*`POST` /pet Add a new pet to the store      Parameter  Add tags //add new query param demo    Request  Changed response : [application/xml]  Changed response : [application/json]*`GET` /pet/findByStatus Finds Pets by status      Parameter    Return Type  Changed response : [200] //successful operation*`GET` /pet/findByTags Finds Pets by tags      Return Type  Changed response : [200] //successful operation*`DELETE` /pet/{petId} Deletes a pet      Parameter  Add newHeaderParam*`POST` /pet/{petId}/uploadImage uploads an image for pet      Parameter  petId Notes ID of pet to update change into ID of pet to update, default false*`POST` /user Create user      Request  Changed response : [application/json]*`POST` /user/createWithArray Creates list of users with given input array      Request  Changed response : [application/json]*`POST` /user/createWithList Creates list of users with given input array      Request  Changed response : [application/json]*`GET` /user/login Logs user into the system      Parameter  Delete password //The password for login in clear text*`GET` /user/logout Logs out current logged in user session*`PUT` /user/{username} Updated user      Request  Changed response : [application/json]*`GET` /user/{username} Get user by user name      Return Type  Changed response : [200] //successful operation

JSON

{"changedElements": [...],"changedExtensions":null,"changedOperations": [...],"compatible":false,"deprecatedEndpoints": [...],"different":true,"incompatible":true,"missingEndpoints": [...],"newEndpoints": [        {"method":"GET","operation": {"callbacks":null,"deprecated":null,"description":"Returns a single pet","extensions":null,"externalDocs":null,"operationId":"getPetById","parameters": [                    {"$ref":null,"allowEmptyValue":null,"allowReserved":null,"content":null,"deprecated":null,"description":"ID of pet to return","example":null,"examples":null,"explode":false,"extensions":null,"in":"path","name":"petId","required":true,"schema": {...},"style":"SIMPLE"                    }                ],"requestBody":null,"responses": {...},"security": [                    {"api_key": []                    }                ],"servers":null,"summary":"Find pet by ID","tags": ["pet"                ]            },"path":null,"pathUrl":"/pet/{petId}","summary":"Find pet by ID"        }    ],"newSpecOpenApi": {...},"oldSpecOpenApi": {...},"unchanged":false}

License

Thanks