Your API is the contract between the consumer and your server
What is oasdiff?
oasdiff is an OpenAPI Specification Diff Tool which can be used as a command-line utility or golang package to compare two versions of OpenAPI specifications (OAS) and identify the differences or changes between them. It helps in detecting breaking changes, additions, or modifications made to an API's contract over time.
The oasdiff tool analyzes the structure and content of the OpenAPI specifications, typically in JSON or YAML format, and provides a comprehensive diff report highlighting the changes between the two versions. The tool can compare various aspects of the specifications, including endpoints, request/response parameters, data types, security definitions, and more.
The generated diff report typically includes information such as added, removed, or modified components, highlighting the exact differences and providing insights into potential breaking changes. This can be valuable during the development and maintenance of APIs, allowing developers to assess the impact of changes and ensure backward compatibility.
oasdiff can be useful in continuous integration/continuous deployment (CI/CD) pipelines, where it can automatically compare API versions to ensure that modifications are thoroughly reviewed and tested before deployment.
For usage instructions and additional details, see the oasdiff repository on github.
What is OpenAPI?
The OpenAPI Specification (OAS) is a standardized, machine-readable format for describing and documenting RESTful APIs. It provides a clear and consistent way to define API endpoints, request and response parameters, data types, authentication methods, and more. The specification promotes API interoperability and simplifies the process of building, testing, and consuming APIs by developers and tools.
Why a dedicated diff tool for OpenAPI?
A regular diff tool, like the unix diff cmd-line, compares files line by line, an OpenAPI diff tool understands the hierarchal structure of the OpenAPI document and compares corresponding elements such as APIs, parameters, properties etc., to each other, even if they are deeply embedded or on different lines across the two files.
Typical use-cases of an OpenAPI diff tool
An OpenAPI diff tool can be used to track changes made by developers to APIs, understand their context and impact, provide documentation for API consumers who want to track functionality changes including bug fixes and upgrade paths, and most importantly, to detect breaking-changes and even prevent them.
How to use an OpenAPI diff tool
The diff tool can be used in different stages of the development process:
While coding, check that you are not breaking the API
When committing code changes into git, check that you are not breaking the API
When releasing a version, create a changelog for consumers
What are breaking-changes?
OpenAPI (previously known as Swagger) is a rich specification with a complex hierarchal structure, and many elements and interdependencies. OpenAPI specs define the REST API endpoints, their parameters, headers and bodies, responses and schemas and much more. During software development iterations, OpenAPI specs are often updated to reflect new or modified functionality. For example, when changing the type of a parameter from a string to an enum. This may require a change to the client. If the client isn't updated simultaniously, the application may break.