How can I diff Swagger to compare and find the differences of 2 versions

Question

if I can get a guide on how I can use a diff tool or some inbuilt diff in swagger to compare 2 swagger API versions and then I can use it to add documentation notes.

Answer 1

If you use swagger 2 specification, you could use the swagger diff library.

There is a maven plugin for Java application : https://github.com/Sayi/swagger-diff

Or use Agnostic Java application by comparing the swagger file https://github.com/civisanalytics/swagger-diff

And for open api 3 specification you could use open api diff (you could find maven plugin or binary diff tool)

All these tools let to get a details report about the changed, breaking change between the specification file.

And then if you want, you could include the step in continuous integration step. If you have only one file to describe all version api, you should find a way to split version file to execute the diff.

Answer 2

You can check out Swagger Brake which allows to detect breaking changes between two API schemas.