Andrew Harry

andrewharry.com

Automated Release Notes

Managing API releases can be daunting, with multiple versions and changes to consider, it’s easy to get bogged down in manual comparisons and documentation.

Unfortunately, it’s easy to miss breaking changes when numerous APIs are involved in a release, potentially causing major issues in production.

Today, I’ll show you how to leverage free tools (OpenAPI-diff and PowerShell) to create a simple automated release process that highlights added, changed, deprecated, and removed APIs, and most importantly, any breaking changes.

Main objectives:

  • Outline which APIs have been added, changed, deprecated or removed.
  • Identify any breaking changes to previously published APIs.
  • Provide detailed info on the low-level changes.

Assumptions:

  • You generate your Swagger files from source code.
  • You have Podman or Docker installed on your computer.

Starting Point - Capturing the data

In order to perform this analysis, we need to be able to compare the current changes against the previous version of the APIs.

Step 1 - Retain the API swagger files

If you don’t have the previous version, you might be able to regenerate it by using Git to go back in time.

You should create a new routine of retaining all your API swagger files for each release.
I keep the API swagger files in a docs/release-notes/ folder at the root of the project.

Each set of swagger files is kept in a subfolder named for the release number. i.e. /docs/release-notes/2.1.0


Comparing Versions

The tool I use to compare versions is called OpenAPI-diff . It is based on java, which I would rather avoid installing - thankfully it can be run as a docker command (or podman).

This powershell script conveniently runs the tool inside podman.

  param (
    [Parameter (Mandatory=$true, Position=0, ValueFromPipelineByPropertyName=$true)]
    [ValidateNotNullOrEmpty()]    
    [string] $previous_version,
    [Parameter (Mandatory=$true, Position=1, ValueFromPipelineByPropertyName=$true)]
    [ValidateNotNullOrEmpty()]    
    [string] $new_version,
    [Parameter (Mandatory=$true, Position=2, ValueFromPipelineByPropertyName=$true)]
    [ValidateNotNullOrEmpty()]    
    [string] $sourceFolder,
    [Parameter (Mandatory=$true, Position=3, ValueFromPipelineByPropertyName=$true)]
    [ValidateNotNullOrEmpty()]    
    [string] $swaggerFile
  )

  $localFolder = Resolve-Path -Path $sourceFolder
  
  # Capture console output and generate markdown in one command
  $releaseNotes = podman run --rm -t -v ${localFolder}:/local openapitools/openapi-diff:latest /local/$previous_version/$swaggerFile /local/$new_version/$swaggerFile --markdown /local/$new_version/${swaggerFile}.changes.md | Tee-Object -Variable releaseNotes

  # Write the release notes to a file
  $releaseFile = Join-Path $sourceFolder "$new_version-release-notes.md"
  Out-File -FilePath $releaseFile -InputObject $releaseNotes

Running the script

powershell .script-name.ps1 2.0.0 2.1.0 -sourceFolder:<insert-folder-path-here> -swaggerFile:<swagger-file-name-here>

Summary & API Change files

The above script generates two files for given Swagger file.
The first one is a summary page which the OpenAPI-diff tool outputs to the console - this is stored as /docs/release-notes/2.1.0-release-notes.md

The second script is the detailed analysis of changes between the two versions and saved as /docs/release-notes/2.1.0/<swagger-filename>.changes.md.

Strangely, this second file doesn’t contain information regarding whether an API change is breaking or not.

Commit the release notes to source

Now that you have the release notes, take the time to review the changes it detected. Are there any surprises? Did an API change unexpectedly? Did a new API version inadvertently change the model for the previous one?

If your analysis finds an issue, you might need to hotfix the release to address the concerns.

TIP - Check-in the release notes into source control.

Conclusion

The OpenAPI-diff tool is pretty handy for automating the comparison of two OpenAPI Swagger files. Sometimes the tool is a bit sensitive, with some minor field descriptions in the swagger file causing the API to appear changed.

This is no substitute to integration/regression testing to detect breaking changes. This tool is limited to only analyzing the Swagger files and can’t detect if the internal business logic has changed.

I hope you start using it as part of your team’s API release process.

Contents