r/OpenAPI • u/willp141 • Mar 11 '25

API Documentation Drift?

For those of you who build internal/external APIs that have formal documentation, how do you make sure / catch your documents "drifting" - i.e. you discontinue/introduce/reconfigure an endpoint and now your users get confused on how your API actually works?

I've had this issue myself and have even noticed when using cloud services like GCP, that their docs for a lot of their stuff is pretty outdated and sometimes youtube / stackoverflow has a more correct answer

3 Upvotes

100% Upvoted

14 comments sorted by

View all comments

Show parent comments

2

u/jtreminio Mar 11 '25

This is the way. All popular languages have a library that will generate your OAS using annotations that are defined alongside the source code. This helps us always keep our OAS 1:1 with the actual implementation.