Recommended tool for RAML 1.0 to HTML


#1

I’m currently developing a RAML 1.0 API and would like to publish the documentation for others to review.

After looking at a few of the tools out there I realised that they only have support for 0.8

I know it’s still early days but if anyone can suggest a tool that will generate the documentation as HTML (or perhaps some other format) then I’d been keen to look at it.

The only option I’ve got so far is to view the documentation within Atom, which is possible, but not quite practical.

Thanks.


#2

@dubs, I have seen some repo that actually implemented some support for 1.0 into raml2obj that underpins the raml2html website. Maybe you should have a look. https://github.com/type-raml/raml2obj

It also seems that you can switch off the parsers validation and use what is there https://github.com/raml2html/raml2html/issues/156.


#3

I think this is an important question for the RAML team. We’re using RAML extensively, and its great. But pragmatically speaking, much as we’d like to chip in and help with the tooling, we just don’t have time or resources for it.

We’ve already had to freeze our use of RAML at 0.8 due to lack of tooling to generate HTML from the RAML (one of the main benefits we get from it). If the situation persists, eventually we’ll need to switch to some other tool like swagger.


#4

@abraae,

When you say you had to freeze at 0.8 due to lack of tooling, are you saying raml2html was a tool you could not use for documentation purposes? If that is the case, what tooling in swagger provides more robust output? Is raml2html lacking in any way that you can not use it for your purposes?


#5

What I mean is that we have frozen our RAML at 0.8, since raml2html works with 0.8, but not with 1.0 (https://github.com/raml2html/raml2html/issues/156).

So if we were to move to RAML 1.0, we would have no way to generate html from it - which is the main value we get from RAML.

We haven’t looked into swagger at this stage, as we are really hoping that someone will get raml2html working with RAML 1.0. We love RAML. However not having tooling to extract html documents from the API specs is a deal breaker for us.


#6

Ah…ok. Well, RAML 1.0 has a few big additions that may take some time to get raml2html 1.0 fully supported. I believe @Mike_Stowe and a few others are working on it as the 1.0 spec nears completion. I suspect it will be some months before it is ready though, but rest assured it is in the works.

RAML 1.0 with annotations and YAML types is going to be interesting to see what unfolds in the community as well. With annotations, you could add all sorts of cool capabilities, but the parsers for things like docs, sdks, etc will have to be aware of specific annotations and their definitions in order to utilize them in generated output. For example, the Try it now feature, which I am not a fan of, could be greatly enhanced by adding an annotation that can indicate a request chain to call that would retrieve the data that might be needed for the try it now request. Postman makes this pretty easy with its collections, but Try it now requires some copy/paste usually from previous requests (possibly) to work. A parser that could utilize annotation data to figure out the 1 or more requests needed to pull results from to feed the try it now request about to be made would make it easier to use the feature in HATEOAS like APIs. HATEOAS is another area annotations might be able to be used, to name a couple.


#7

Hi @abraae, I fully understand your problem. I would still recommend to use 0.8 at this moment as long as 1.0 is not GA (we will be there around mid April). I have already seen a fork for raml2obj that supports 1.0 here and there is a little trick to enable OOTB support for RAML 1.0 RC1 here.

People are already implementing what you need, but I guess at the same time waiting for 1.0 to be closed I guess.


#8

Thanks Christian! And props again to RAML, it has been quite a game changer for our business. We have a lot of APIs, and RAML + raml2html has really given us a great single source of truth to base development and communications with third parties around.


#10

I have updated the raml2obj project that powers the raml2html project to support RAML 1.0 RC1 in a dev branch here.

the only think left is to update raml2html to at least have a develop branch as well with that. It’s on my agenda :wink:


#11

Exciting news Christian!


#12

There is a branch for an experimental support of RAML 1.0 for raml2html now. The only problem is to visualize the type system. Its a bit tricky since you have to think about the best way to render a very powerful and expressive language :slight_smile: Any help here is much appreciated. Maybe we can collect ideas and then follow up incorporating that into the templates.


#13

Great news! We are heavily into json schema, so can’t offer any real input there. We’re building a runtime validator that checks outgoing req


#14

(oops) … checks outgoing request bodies and incoming responses for conformance to the json schema referenced in the RAML. So for us, we’ll probably either not use the new types, or convert them into json schema so the validator can continue to work.

FWIW, I imagine the visualization might involve composing the set of fields applying to the specific API (via inheritance etc), and then rendering an item for each of them (pretty much like the RAML definition).

In an ideal world, we could “visualise as json” I guess!


#15

That is one idea, indeed. There is currently someone who tries to implement the rendering of RAML types into raml2html. Any help is always appreciated. :wink:

Adding the link: https://github.com/raml2html/raml2html/pull/194


#16

May be an alternative of raml2html tool here :


It is generating RESTful API documentations written in RAML and supports 1.0


#17

This is great but I like the style of raml2html :grin:


#18

Hi Christian, the link is broken or doesnt exist. Can you explain me a little how did you do to use raml2html with raml 1.0, I´ve written a lot documentation in raml 1.0, but, for example the use of Library doesnt work, and other new features, is frustraiting. I have changed the validation in the code of raml2html, it´s ok, but the new features doesnt work. I don´t now the people of Mule Soft recommend so much this version, but there is no support in raml 1.0 . Thanks.


#19

It seems to me, ramlo doesnt work with all the new features of raml 1.0


#20

Hi Jose, look into https://github.com/raml2html/raml2html/issues/254#issuecomment-250816288. Kevin already published a beta version that he would be happy to receive feedback :wink:


#21

It works, thanks Christian, Kevin. Sure with the feedback about the beta version. In a first view is awesome :thumbsup: