How do display a RAML file?


#1

Hi. I’m a technical writer who is new to RAML. I’ve created an API spec using RAML and would like to display it for my team to take a look at. I’m thinking this is by using the api-console but I’m not quite sure whether to ‘include’ the console or use an

Another option would be the raml2wiki plugin. If I generated wiki markup from that plugin and put it on Confluence would I be able to test the API spec?

Thanks.
Michael


#2

You could use API Console… or you can download the RAML2HTML node project, which is pretty easy to set up if you have node installed. You can even get a node docker container running, set up raml2html in that, and use that without having to set up node on your machine directly. That will generate HTML output that is pretty nice.


#3

Thanks. I used the raml2html which seemed to stop generating the html halfway into my raml file. I also used the raml2wiki script which generated good markdown but didn’t have the testing option. What exactly does ‘include’ mean when it refers to that as an option?


#4

If you deploy your API on the JVM, then I suggest you take a look at raml-doc.

It’s a pure Java implementation that can easily be embedded in the same app where your API runs. It comes with a servlet binding but it’s easy to integrate with whatever HTTP stack you use (I integrated it in a JAX-RS resource).

On top of generating and serving the HTML doc for your RAML spec, it can also serve the spec itself and its schemas into one convenient zip archive.

Yep, I’m a big fan :wink:


#5

Thanks for this info. I’m going to check it out. I’ll let you know if I have any questions.