Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/openapitools/openapi-diff
Utility for comparing two OpenAPI specifications.
https://github.com/openapitools/openapi-diff
api diff openapi openapi-diff openapi-specification openapi3 swagger
Last synced: about 4 hours ago
JSON representation
Utility for comparing two OpenAPI specifications.
- Host: GitHub
- URL: https://github.com/openapitools/openapi-diff
- Owner: OpenAPITools
- License: apache-2.0
- Created: 2017-12-12T00:39:30.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2024-04-29T10:01:12.000Z (5 months ago)
- Last Synced: 2024-05-01T12:37:25.166Z (5 months ago)
- Topics: api, diff, openapi, openapi-diff, openapi-specification, openapi3, swagger
- Language: Java
- Size: 1.25 MB
- Stars: 751
- Watchers: 20
- Forks: 153
- Open Issues: 85
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# OpenAPI-diff
Compare two OpenAPI specifications (3.x) and render the difference to HTML plaintext, Markdown files, or JSON files.
[](https://github.com/OpenAPITools/openapi-diff/actions?query=branch%3Amaster+workflow%3A"Main+Build")
[](https://sonarcloud.io/dashboard?id=OpenAPITools_openapi-diff)
[](https://search.maven.org/artifact/org.openapitools.openapidiff/openapi-diff-core)
[](https://gitpod.io/#https://github.com/OpenAPITools/openapi-diff)
[](https://join.slack.com/t/openapi-generator/shared_invite/zt-12jxxd7p2-XUeQM~4pzsU9x~eGLQqX2g)
[](https://hub.docker.com/r/openapitools/openapi-diff)
[](https://hub.docker.com/r/openapitools/openapi-diff)
[](https://hub.docker.com/r/openapitools/openapi-diff/tags)
# Requirements
* Java 8
# Feature
* Supports OpenAPI spec v3.0.
* Depth comparison of parameters, responses, endpoint, http method (GET,POST,PUT,DELETE...)
* Supports swagger api Authorization
* Render difference of property with Expression Language
* HTML, Markdown, Asciidoc & JSON render
# Maven
Available on [Maven Central](https://search.maven.org/artifact/org.openapitools.openapidiff/openapi-diff-core)
```xml
org.openapitools.openapidiff
openapi-diff-core
${openapi-diff-version}
```
# Docker
Available on [Docker Hub](https://hub.docker.com/r/openapitools/openapi-diff/) as `openapitools/openapi-diff`.
```bash
# docker run openapitools/openapi-diff:latest
usage: openapi-diff
--asciidoc export diff as asciidoc in given file
--debug Print debugging information
--error Print error information
--fail-on-changed Fail if API changed but is backward
compatible
--fail-on-incompatible Fail only if 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 use given header for authorisation
--html export diff as html in given file
--info Print additional information
--json export diff as json in given file
-l,--log use given level for log (TRACE, DEBUG,
INFO, WARN, ERROR, OFF). Default: ERROR
--markdown export diff as markdown in given file
--off No information printed
--query use query param for authorisation
--state Only output diff state: no_changes,
incompatible, compatible
--text export diff as text in given file
--trace be extra verbose
--version print the version information and exit
--warn Print warning information
```
## Build the image
This is only required if you want to try new changes in the Dockerfile of this project.
```bash
docker build -t local-openapi-diff .
```
You can replace the local image name `local-openapi-diff` by any name of your choice.
## Run an instance
In this example the `$(pwd)/core/src/test/resources` directory is mounted in the `/specs` directory of the container
in readonly mode (`ro`).
```bash
docker run --rm -t \
-v $(pwd)/core/src/test/resources:/specs:ro \
openapitools/openapi-diff:latest /specs/path_1.yaml /specs/path_2.yaml
```
The remote name `openapitools/openapi-diff` can be replaced with `local-openapi-diff` or the name you gave to your local image.
# Usage
openapi-diff can read OpenAPI specs from JSON files or HTTP URLs.
## Command Line
```bash
$ openapi-diff --help
usage: openapi-diff
--asciidoc export diff as asciidoc in given file
--debug Print debugging information
--error Print error information
-h,--help print this message
--header use given header for authorisation
--html export diff as html in given file
--info Print additional information
--json export diff as json in given file
-l,--log use given level for log (TRACE, DEBUG,
INFO, WARN, ERROR, OFF). Default: ERROR
--markdown export diff as markdown in given file
--off No information printed
--query use query param for authorisation
--state Only output diff state: no_changes,
incompatible, compatible
--fail-on-incompatible Fail only if API changes broke backward compatibility
--fail-on-changed Fail if 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 and exit
--warn Print warning information
```
## Maven Plugin
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.
```xml
org.openapitools.openapidiff
openapi-diff-maven
${openapi-diff-version}
diff
https://petstore3.swagger.io/api/v3/openapi.json
${project.basedir}/target/openapi.yaml
true
true
${project.basedir}/../maven/target/diff.txt
${project.basedir}/../maven/target/diff.json
${project.basedir}/../maven/target/diff.md
my/config-file.yaml
false
```
## Direct Invocation
```java
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);
//...
}
}
```
### Render difference
---
#### HTML
```java
String html = new HtmlRender("Changelog",
"http://deepoove.com/swagger-diff/stylesheets/demo.css")
.render(diff);
try {
FileWriter fw = new FileWriter("testNewApi.html");
fw.write(html);
fw.close();
} catch (IOException e) {
e.printStackTrace();
}
```
#### Markdown
```java
String render = new MarkdownRender().render(diff);
try {
FileWriter fw = new FileWriter("testDiff.md");
fw.write(render);
fw.close();
} catch (IOException e) {
e.printStackTrace();
}
```
#### Asciidoc
```java
String render = new AsciidocRender().render(diff);
try {
FileWriter fw = new FileWriter("testDiff.adoc");
fw.write(render);
fw.close();
} catch (IOException e) {
e.printStackTrace();
}
```
#### JSON
```java
String render = new JsonRender().render(diff);
try {
FileWriter fw = new FileWriter("testDiff.json");
fw.write(render);
fw.close();
} catch (IOException e) {
e.printStackTrace();
}
```
### Extensions
This project uses Java Service Provider Inteface (SPI) so additional extensions can be added.
To build your own extension, you simply need to create a `src/main/resources/META-INF/services/org.openapitools.openapidiff.core.compare.ExtensionDiff` file with the full classname of your implementation.
Your class must also implement the `org.openapitools.openapidiff.core.compare.ExtensionDiff` interface.
Then, including your library with the `openapi-diff` module will cause it to be triggered automatically.
# Examples
### CLI Output
```text
==========================================================================
== 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
```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
```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
openapi-diff is released under the Apache License 2.0.
# Thanks
* Adarsh Sharma / [adarshsharma](https://github.com/adarshsharma)
* Quentin Desramé / [quen2404](https://github.com/quen2404)
* [Sayi](https://github.com/Sayi) for his project [swagger-diff](https://github.com/Sayi/swagger-diff)
which was a source of inspiration for this tool