How to compare two OpenAPI files?

Laradoc doesn't yet provide a built-in way to generate a changelog for changes made to your Laravel API between different versions. It only generates one OpenAPI specification file per commit and lets you switch between them.

However, by downloading the OpenAPI specifications we generated, you can use OpenAPI-diff, which is a tool to easily compare two specifications and identify the differences between them. This can be a helpful way to ensure backward compatibility and detect breaking changes on your API.

1. Download the JSON specifications

Start by downloading the OpenAPI specifications generated by Laradoc. You can open your Laravel project, select your commit and click on "Download OpenAPI file".

2. Install OpenAPI-diff

Next, you'll need to install OpenAPI-diff. This can be done easily with npm:

npm install -g openapi-diff

If you prefer to use Docker instead, there is an image an Docker Hub.

3. Compare the specifications

You can now compare two OpenAPI specifications. Run the following command:

openapi-diff old-spec.json new-spec.json

Or if you're using Docker:

docker run --rm -t \
  -v $(pwd):/specs \
  openapitools/openapi-diff:latest /specs/old-spec.json /specs/new-spec.json

You should get a change log in plaintext format that looks like this:

4. Generate a report in HTML

If you want to generate a more visually appealing report, you can use the --html option to output an HTML report. This can be done by running the following command:

openapi-diff old-spec.json new-spec.json --html report.html

This will generate an HTML report and save it to a file called report.html. You can then open the file in your web browser to view the differences between the two specifications in a more user-friendly format.

In conclusion, OpenAPI Diff is a user-friendly and powerful tool for comparing two OpenAPI specifications. When used with Laradoc, it can help you generate changelogs and ensure that your Laravel API remains consistent and backward-compatible.