Don't get me wrong. I think RAML and it's associated tools have a lot of promise, and are clearly superior (on paper) to other offerings, but they are far from bulletproof or turnkey in my opinion. My "abysmal" experience stems from the fact that nothing I have tried to accomplish with these tools worked out of the box, on the first try. Just so we're clear on what I have tried:
- parsing RAML with the JS parser (hence this post)
- executing RAML-defined services using the JS client downloaded from the API console
- designing RAML interface in API designer with heavy use of includes
- running API notebook with the intent of exercising the API defined above
To date, none of these exercises have come without more than their fair share of pain. The JS code parser use case should have been very simple. I didn't give it more than a trivial RAML example to work with and it failed for the above reason, which makes absolutely no sense. And I still have not determined the cause.
The second use case, the downloaded API just doesn't work. It either hangs completely or errors out after a significant delay. I can see the request hit the server but it never completes successfully. If I manually compose the URL for the same request it works just fine every time. Could be in my RAML definition but there's no way to know for sure. I'll have to debug Popsicle to figure out what's going on.
The third use case is frustrating due to inadequate error reporting and destructive quirks in the editor. Many, many times I'd get a red outline box on the editor window but no indication of where the error is. When the error marker does show up it is misplaced and references something buried in an include. I would prefer to see those errors on the included file, but of course there is no error reported there. The API designer also constantly lost changes I had made or overwrote the contents of one file with another when rapidly switching between files, which is pretty much required because of the issue above. I finally had to abandon the API designer altogether in favor of a text editor with RAML/YAML syntax support. (Also, if you're going to store the files in localStorage, at least give me a download/export option.)
The fourth use case fails because of the github provider was missing (or some similar error). I think the integration with github is cool, but don't want to have to figure that out just to poke around in an API I have defined locally. Admittedly, I did not spend a lot of time trying to make this work, and am not inclined to do so until the more serious concerns above are addressed.
In contrast, everything I asked Swagger to do, it did correctly and without hesitation or intervention of any kind. I tested it extensively to the extent that this tool supports some of the things that RAML+tooling is supposed to do. Swagger may not have as rich a feature set as RAML+tooling, but it works every time. I am sorry to say that RAML, et. al., does not, at least for me.
For the record, I have already recommended RAML+tooling over Swagger for a project my company is pursuing and I am dearly hoping that wasn't a mistake. The fact that the JS client downloadable from the API console does not work (at all) is a real deal breaker though.