I was hopeful starting this article. Because I do think we need something better than OpenAPI for self-documenting APIs...

The idea of an interactive tutorial is great, but as others have mentioned, likely very difficult to maintain over time.

I built this because I had the same idea: https://github.com/hitchdev/hitchstory

If your specification is self rewriting, can be tested and can be used to generate docs then maintenance costs plummet.