I've been looking at this (we have a lot of docs and our API docs are all written in asciidoc). I don't think the value of OpenAPI is in the documentation, though it seems pretty thorough.

There are a lot of benefits for the API producer in terms of tooling and the ecosystem.

But that tooling also helps the consumer. Look at all the tools listed here: https://openapi.tools/ Those that would be helpful to me as a consumer of an API are:

   * Documentation
   * Learning
   * Mock servers (for testing)
   * Some of the tools under misc
   * SDK Generators. Most people don't want to consume an API using REST, they want to use their fav language to do so

I asked in a slack full of developer relations folks about alternatives to OpenAPI for defining REST APIs and didn't hear any good alternatives.

SlateDocs looks really nice, though. As sibling comments have pointed out, you can have both.