Ruby/Rails tooling


#1

It’d be great to have some tooling built to making using RAML more attractive to Ruby/Rails developers. Some things I can imagine being useful would be:

  • A rubygem which provides an API client to an arbirtrary RAML document.
  • Scaffolding Rails routes and controllers from a RAML document
  • An automated test that verifies your application correctly implements a RAML document

I think the server tools would encourage design-first approaches to building APIs, and having an automatically-generated, robust client would save developers considerable time.

Does anyone else have any ideas?


#2

Yes, yes, and yes! And since people are starting to develop these tools in multiple languages, there should be some opportunities for sharing approaches as these are built out.


#3

@usarid
Are you aware of any ruby tools currently in progress? I am potentially going to address 1st and 3rd points mentioned by @tommy, wouldn’t want to do same work twice.


#4

Hi @kgorin,
I found this project a couple of weeks ago looking for something similar: https://github.com/mishkinf/raml-ruby.
I didn’t have time to give it a try yet, but maybe it’s useful for you.
I’ve also read and commented to these people on Twitter: https://twitter.com/jlebrech/status/445894464587169792.

I hope you find this information useful. Please, let me know about your progress and if there is something I can help you with.

Cheers!


#5

This is very skeleton project, so I’ve just started all over.

I am working on the parser this and next week on my daily job, so it should move pretty quickly. I’ll post the link here next week.


#6

@kgorin These are great news!!
Don’t hesitate in contacting me if some help is needed (either to bring up ideas, test, write some docs, etc).

Regards.


#7

Raml ruby will live here https://github.com/coub/raml_ruby - very early version.
I think I will post the link again when there is usable version ready to be released, any suggestions are welcome.


#8

Because there was a lack of a ruby parser for RAML, I implemented the behavior mentioned by using a the javascript raml parser together with execjs. The result was quite succesful but a native ruby approach would be best and much more manageable!


#9

I would like to hear any ideas on output formats for documentation - markdown, html anything else?


#10

Dynamic documentation?

Static documentation:

  • Markdown provides a nice pro: Simplicity and easiness for publishing (i.e: an API code in github and documentation in github too).
  • HTML is a nice option too, since it can provide some dynamism w/o losing easiness for publishing.
  • PDF: It sounds old-fashion, but it could be a good printable version (maybe just converting from MD or HTML to PDF).
    I would explore RAML2HTML project: https://github.com/kevinrenskers/raml2html
    Last time I talked to Kevin, I exposed the idea of having the same project exporting to other formats too (MD). I know he is working actively on the project, but I don’t know if he is tackling down that feature. It could be interested for you to contribute if you find it useful.

Let me know if I can help you with this!
Cheers!


#11

Both are great suggestions!

I have updated readme for the lib, with brief usage instructions. Also there is todo list, so if anyone wants to help feel free to contact me.


#12

Hi kgorin,

I am very intensely using RAML as documentation first development at my company. We are programatically using it to write tests and capture unexpected responses we may send that don’t match the schemas.

Unfortunately, we are still pointing at https://github.com/eliaslevy/raml_ruby . It’s a very much complete RAML Ruby parser. Would there be any way we could start updating the main raml_ruby repository with it? I would be more than happy to contribute to this project, and even maintain it if it was necessary.

Pleases let me know what do you think about this. I really wish we can get the Ruby community to embrace RAML, and use and create tools around it.

Thanks,

Pol


#13

@polmiro - hope you got your answer already?


#14

Hi Pol,

it’s now merged.


#15

Hi @kgorin - how far could you go with your project relating back to the initial post?


#16

Hi,

I won’t have time to implement 3rd point anytime soon, so feel free to start working on it if you wish.


#17

@kgorin - that wouldn’t be much effective as I have not the knowledge in Ruby/Rails to do it :wink: Is anyone interested in doing point 2? There is a MuleSoft project which is kind of a handlebars engine for RAML where you have to only create your own project and template based on it. That should give you the ability to easily create something for Ruby/Rails. I can also help with the NodeJS/Javascript part if needed. Here is the repo and the gitter channel - please let me know if anyone is interested:



#18

Hi christian,

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!

Pol


#19

Gem is now available at https://rubygems.org/gems/raml_ruby.


#20

As I was reading this my thought leaned towards what @christian_vogel said… we’re trying to make progress on getting various SDK generators, among other things, moving forward with the raml-generator project. It’s quite capable for producing SDK, CLI, doc, etc artifacts. As I think (hope??) we’re trying to centralize around this project to get community support building SDKs generators for different languages, maybe a different HTML help system (if the raml2html isn’t enough for some), server side generators for JAX-RS, etc, and other possible artifacts (automated test code, CLIs, etc), it would be ideal if we could get those interested talking with @christian_vogel and @blakeembrey (and maybe myself) to try to coordinate a common SDK usage pattern that we then all try to have language specific generators adhere to.