I really like the idea of OpenAPI: use your input and output data models to document your API, and maybe even stub out the framework for your actual code or a l

I really like the idea of OpenAPI: use your input and output data models to document your API, and maybe even stub out the framework for your actual code or a language-specific SDK. But the reality is that deviations in auth, data types, etc., end up complicating your OpenAPI specs way more than expected. And the tooling that is supposed to stub out doc sites using your OpenAPI specs is all over the place in terms of what is and isn’t supported, and even how the same supported features are implemented. My team ended up making a custom redoc implementation for our docs site (to include better narrative), but the specs are just for documentation, and don’t inform the application or SDKs at all. Reality is so close to the dream, but in my experience, still so far away.