Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/elibracha/openapi-diff
Command line tool to detect breaking changes between two openapi specifications
https://github.com/elibracha/openapi-diff
Last synced: 9 days ago
JSON representation
Command line tool to detect breaking changes between two openapi specifications
- Host: GitHub
- URL: https://github.com/elibracha/openapi-diff
- Owner: elibracha
- Created: 2020-02-09T09:00:23.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2020-09-16T11:56:56.000Z (over 4 years ago)
- Last Synced: 2024-11-07T14:27:08.554Z (2 months ago)
- Language: Java
- Homepage:
- Size: 552 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# OpenAPI-diff
Compare two OpenAPI specifications(3.x) and render the difference to html file or markdown file.
[](https://circleci.com/gh/quen2404/openapi-diff/tree/master)
# Requirements
`jdk1.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 render
# Maven
Available on [Maven Central](https://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22com.qdesrame%22%20AND%20a%3A%22openapi-diff%22)
```xml
com.qdesrame
openapi-diff
1.2.0
```
# Docker
Available on [Docker Hub](https://hub.docker.com/r/quen2404/openapi-diff/) as `quen2404/openapi-diff`.
## 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)/src/test/resources` directory is mounted in the `/specs` directory of the container
in readonly mode (`ro`).
```bash
docker run -t \
-v $(pwd)/src/test/resources:/specs:ro \
quen2404/openapi-diff /specs/path_1.yaml /specs/path_2.yaml
```
The remote name `quen2404/openapi-diff` can be replaced with `local-openapi-diff` or the name you gave to your local image.
# Usage
OpenDiff can read swagger api spec from json file or http.
## Command Line
```bash
$ openapi-diff --help
usage: openapi-diff
--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
-l,--log use given level for log (TRACE, DEBUG,
INFO, WARN, ERROR, OFF). Default: ERROR
--markdown export diff as markdown in given file
-o,--output use given format (html, markdown) for
output in 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
--trace be extra verbose
--version print the version information and exit
--warn Print warning information
```
## 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();
}
```
### 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/com.qdesrame.openapi.diff.compare.ExtensionDiff` file with the full classname of your implementation. Your class must also implement the `com.qdesrame.openapi.diff.compare.ExtensionDiff` interface. Then, including your library with the `openapi-diff` module will cause it to be triggered automatically.
# Example
### 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
```
# License
openapi-diff is released under the Apache License 2.0.
# Thanks
* Adarsh Sharma / [adarshsharma](https://github.com/adarshsharma)
* [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