I actually have built a bunch of tools already in my company around raml_ruby. I can’t release them until raml_ruby is versioned and pushed to rubygems though.
In general lines what I currently have is something like this:
- raml-repository: easily find a payload or a response schema given a RAML file, and http method and an endpoint.
- raml-repository-builder: this kind of the CLI npm package that I use to do a few different things:
- Run a server that displays the RAML in the current folder
- Validate RAML.
- Export the RAML into one single file (I noticed some external tools do not support RAML that use multiple files like I do).
- Build a gem out of a RAML file. Picks up the version defined in the RAML and generates gem that is wrapped around “raml-repository” and gives you access to the payload and the response schemas of you API.
- Release the gem (as of now just to my private’s company repo).
It’s been a pretty nice experience to have a package with your RAML matching always the version in it. I use them the Rails API in two different ways.
- Runtime: I make sure that the payload received in the current endpoint match the parameters in the RAML. Otherwise I stop execution and display nicely some errors explaining why the request is not valid. I also use it before sending the response back (in development) so that we make sure that what we have always matches the schema in the RAML.
- Test: I have a little helper that I use to quickly write some basic request specs of the API endpoints, doing something like “expect(response).to match_raml_response(200)” when testing a successful response. Similarly when testing error responses.
I haven’t worked on generators, but it’s definitely something worthwhile to look at.
Regarding the last point: “An automated test that verifies your application correctly implements a RAML document”, I have not found a good way to approach this. The main reason is that one has to usually prepare data before each endpoint/response is tested, so it seems very hard to try automate it so ambitiously. I have been happy with my test helpers. But I’m definitely open to new ideas, so if you have any tips, feel free to ping me!