Using AI To Detect API Documentation Drift
AI can compare route definitions, OpenAPI specifications, SDKs, release notes, source code, and published documentation to identify discrepancies before your customers do
AI can compare an API with its documentation by identifying differences between the implementation, OpenAPI specification, software development kit (SDK), release notes, and published documentation. Those differences can reveal places where the documentation has drifted away from the product.
API Docs are often generated from an OpenAPI specification, but that doesn’t guarantee it reflects the API our customers are actually using. Every release creates another opportunity for our docs to drift away from our product. Even well-maintained doc sets gradually fall out of alignment as our software evolves.
Why Does API Documentation Drift?
API Docs drift because software changes faster than every source describing it can be updated. Each update to a release introduces changes. An endpoint is added. Maybe a parameter changes or an software development kit (SDK) gains a convenience method. Our release notes might announce a new capability, while our tutorials and examples, are (maybe) updated later — or not at all.
These are typical situations and they rarely reflect poor documentation practices.
The information describing an API is often maintained in different repositories, formats, and is managed by different teams sometimes using differing approaches and tools. Small differences accumulate until the implementation, OpenAPI specification, SDKs, release notes, and published documentation no longer describe exactly the same product.
Many organizations don’t discover those inconsistencies until customers encounter and report them.
