Automating How DevNet Produces API Changelogs
Go “Behind the Curtain” with DevNet Engineering
A single developer engaged on a product may be very linked to the APIs that they expose. As they modify it over time, they’ll individually monitor what has modified from model to model. As a staff grows, the duty of updating the changelog plus launch notes falls to a product supervisor or a group of builders the place element might fall by way of the cracks. Solely when a third occasion developer making an attempt to make use of the API finds that one thing doesn’t work as anticipated or documented – is there a correction to the changelog and/or API.
DevNet engineering faces the same problem for the entire APIs we at present doc on developer.cisco.com. The problem is compounded by the governance required throughout many product teams and stakeholders. Some teams preserve a constant narrative of adjustments and doc these within the launch notes plus changelog sections of their API documentation. Different groups might battle for assets or time. In these instances an automatic answer is required.
Automated changelog answer
Our staff has tackled this problem by using part of the API improvement course of that has change into more and more frequent, using OpenAPI specs. The OpenAPI Initiative defines this as “…a typical, programming language-agnostic interface description for HTTP APIs, which permits each people and computer systems to find and perceive the capabilities of a service with out requiring entry to supply code, extra documentation, or inspection of community site visitors.”
Since most of our product groups produce an OpenAPI Spec (OAS, now v3 or OAS3 for brief) – we will use that file to automate the era of properly displayed documentation. Moreover, utilizing internally developed instruments, we will examine variations of an OAS file, which permits detection of what has modified – i.e., a changelog.
API adjustments are categorized as new, deprecated, modified, and breaking. So, we have now all the data wanted to create automated changelogs which replicate a lot of the info a developer must see what has modified.
Nonetheless, an automatic changelog doesn’t take note of the writing of a small narrative of why adjustments had been made, or the elimination of unimportant element. The best strategy finally ends up being a mix of automation with human oversight / enhancing, much like AI-generated textual content.
What about your DevRel content material groups? Have you ever used automation to deal with the API changelog problem, or are you continue to doing it by hand? Tell us within the feedback.
Check out our API documentation throughout merchandise to get a way of the scope of our problem.
Share:
