We’re using RAML (structure) + Json Schema (JSON endpoints) to document our APIs. It makes it easier to write a schema because you can validate examples against it, and also allows us to use the schema to validate requests and responses in Behat tests. We’re also starting to use the schema to validate endpoint inputs.

I think a well-structured, machine-readable schema is a great tool. And you can generate HTML documentation from it too, although we haven’t used that option yet (all our APIs are currently internal).