I'd suggest RAML for pure documentation. Its way of structuring resources is nested with the URI, so UI generators can use that information to group together in

I'd suggest RAML for pure documentation. Its way of structuring resources is nested with the URI, so UI generators can use that information to group together in the docs. Also it supports union types for request/resp. Which means that you can template a URI and have multiple response schemas to go with different values of the template. Unlike swagger which forces you to enumerate every endpoint if you want them to have different response schemas, which is very ugly for logically grouped sets of resources which aren't explicitly part of a collection.