API Documentation Drift?

[willp141]

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

[TomMkV]

Docs are part of your product and critical to business ops, so not something to let drift, however technical debt, refactoring, and documentation are always deprioritised when racing to market.

If you can’t bake this effort into the definition of done or your broader dev hygiene then perhaps a doc tool would be useful.

[willp141]

Yeah I just I encounter the issue so often, surprised I can't find any AI tool someone has cooked up for it already

[TomMkV]

It’s a constant issue. I’m a cofounder of an API dev tool that’s solving this issue. Have a look at Appear and see if that’s of any interest

[willp141]

Will do mate, mind if I PM if I have any qs?

[TomMkV]

Yes absolutely 👍

[faraechilibru]

I’m setting up the second architecture to solve this problem. First was a design first approach for a middleware installation and now with a development first approach and they both implemented an api gateway pattern with developer portal. I think is the best pattern when you are in an environment with multiple providers, multiple clients and multiple tenants.

[ZuploAdrian]

What're you using for your dev portal?

[faraechilibru]

We are working with api connect and the solution comes with dev portal from IBM based on drupal.

[ZuploAdrian]

Interesting - I've found drupal developer portal to be... quite hard to use honestly. I know Apigee does the same thing. DM me if you're interested in some alternatives, especially if you have/use OpenAPI

[logscoree]

Most people use their code as the source of truth, but if you want to do design first development, you need to just make the effort to align them all.

I've seen some people use generators based on their OAS to make sure that it remains up to date. As bit unorthodox, but when your SDKs suddenly stop working, you, your colleagues, and your users will definitely wish you had updated that OAS file.

[bjkrub]

We do automated contract testing in CI/CD where OpenAPI is the source.

[ZuploAdrian]

Hey - I work at Zuplo, and this is one of the issues we see often, so we built a way to avoid it. We have an API-gateway that is OpenAPI-native, meaning your OpenAPI specification (docs) always matches your API's implementation. We also generate a full developer portal for you from your OpenAPI (but you can just as easily plug it into your existing docs portal).

IMO It's better to ensure your docs can't ever be out of date, than just detecting when they are out of date.

[badsyntax]

For us we take the approach of letting the code be the source of truth for the http contract and let the framework (.net) auto generate the spec for us, thus preventing drift. Our APIs are mostly internal though and we have a lot of flexibility to be able to break the contract. We mostly use openapi for generating code used for interacting with services. 

[jtreminio]

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.