Is there a way to detect when a swagger changes?

Question

My coworker, after 2 months of not turning anything in, has been placed under me.

Today they changed some api calls to make something of mine that had been running for months stop working. They changed the name of some fields and how they work.

How can I detect when they do this in the future.

Swagger.io is the swagger i'm talking about.

Answer 1

I know this question is old, but for the sake of people ending up here looking for an answer these days: now there is a solution, called Swagger Diff. It can compare two swagger.json files, and highlight any changes.

• Ruby version: https://github.com/civisanalytics/swagger-diff
• Java version: https://github.com/Sayi/swagger-diff

The Ruby version you can even use in the build process, and fail the build if there's any incompatibility. The Java version currently only shows a list of changes.

Answer 2

Currently, there's no tool to provide diffs between swagger docs, though such a tool has been requested. It won't necessarily be easy to create such a tool since if an operation path is changed, for example, there's no real way of linking between the old and the new.

However, Swagger does not replace proper API version management. Just like any piece of software, APIs need to be controlled. You have the apiVersion property which should be used to indicate such changes.

Answer 3

Ron's right in the larger scheme of things, but if you just need to show that a breaking change occurred, remember that swagger produces a standardized JSON file that you can diff and track in version control. If you have version control on your API code and your swagger output, you can show when someone does something they shouldn't, because the code and the swagger will not be together in the same diff.

In other words, if you track both code and swagger JSON, you can enforce the requirement that both should appear in the same commit diffs, and that the api version be updated according to some standard.