Automating How DevNet Produces API Changelogs

Go “Behind the Curtain” with DevNet Engineering

A single developer working on a product is very connected to the APIs that they expose. As they modify it over time, they can individually track what has changed from version to version. As a team grows, the task of updating the changelog plus release notes falls to a product manager or a collection of developers where detail may fall through the cracks. Only when a 3rd party developer trying to use the API finds that something does not work as expected or documented – is there a correction to the changelog and/or API.

DevNet engineering faces a similar challenge for all of the APIs we currently document on developer.cisco.com. The challenge is compounded by the governance required across many product groups and stakeholders. Some groups maintain a consistent narrative of changes and document those in the release notes plus changelog sections of their API documentation. Other teams may struggle for resources or time. In those cases an automated solution is needed.

Automated changelog solution

Our team has tackled this challenge by utilizing a part of the API development process that has become increasingly common, the use of OpenAPI specifications. The OpenAPI Initiative defines this as, “…a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic.”

Since most of our product teams produce an OpenAPI Spec (OAS, now v3 or OAS3 for short) – we can use that file to automate the generation of nicely displayed documentation. Furthermore, using internally developed tools, we can compare versions of an OAS file, which allows detection of what has changed – i.e., a changelog.

API changes are categorized as new, deprecated, modified, and breaking. So, we have all the information needed to create automated changelogs which reflect most of the information a developer needs to see what has changed.

Still, an automated changelog doesn’t take into account the writing of a small narrative of why changes were made, or the removal of unimportant detail. The right approach ends up being a combination of automation with human oversight / editing, similar to AI-generated text.

What about your DevRel content teams? Have you used automation to tackle the API changelog challenge, or are you still doing it by hand? Let us know in the comments.

Take a look at our API documentation across products to get a sense of the scope of our challenge.

Share: