This is true. I’ve personally had better success documenting APIs with RAML. We found that Swagger caused too many implementation details to bleed into the API that required too much work to fix. This is because Swagger originated in the Java world and was very tightly coupled to an annotation driven approach (which led to very annotation heavy endpoints). We also found that the most interesting stuff we would get form Swagger was contained within string based annotations which wouldn’t be automatically updated when your API changed (which negated the point of Swagger and its tight coupling with your code). I suspect this has improved in the last year or so but I haven’t really investigated.
So back to RAML. RAML allows you to write an API specification in the form of a YAML style document that can be applied to any base URL. It is also possible to generate API clients and (potentially) tests against this document. You also get the actual documentation that can be pointed to a test environment for live examples (similar to Swagger).
The big difference I found between the two was the Swagger is good for documenting existing APIs or evolving new ones as you go. RAML is much better suited to designing APIs and I think the tooling certainly echos that opinion.
However, yes, both tools are more aimed at documenting an API instance rather than standards but I do think RAML would be a much better fit fir at least defining a standard from a technical perspective.
