In a recent article I introduced Slate, a static site generator specifically designed for writing API documentation. This time around, I’m going to look at something which in many ways is even better.
But first, if you’ll indulge me for just a moment, I’d like to begin by quoting myself from that article;
[an] API is only as good as its documentation
I think it’s worth repeating, since it’s all-too-frequently overlooked, and it’s one of the motivations for this short series of articles on some of the tools out there to help you write great documentation.
Slate is a useful tool, but despite the relatively rigid structure of the pages themselves, the actual documentation is pretty freeform.
RAML (RESTful API Modeling Language) provides a structured, unambiguous format for describing a RESTful API. It allows you to describe your API; the endpoints, the HTTP methods to be used for each one, any parameters and their format, what you can expect by way of a response and more.
You can use RAML in a number of ways;
It can be used in the design and specification stage to describe the API you plan to build
You can use RAML to generate documentation
RAML can be used to implement interactive API consoles
You can test against RAML
It be used to generate mock API responses
In this article I’ll primarily look at generating documentation; in a later article I’ll look at how you can integrate RAML into your API testing. But first, let’s look at how to write a RAML document.
Why not use OData, it is open/enterprise/…
Is the problem that it originated in Microsoft, or to abide to a predefined structure instead of doing your own version of everything – a version that is just a little bit wrong.
(By the way, I reinvent the wheel all the time. It is the industry standard)
Not sure anyone reading this will find this helpful, but there is a “movement” among the RAML community around “generation” of anything/everything from RAML. In particular, the raml-client-generator project spun off an abstracted project called raml-generator. That project allows you to build your own nodejs module that requires raml-generator and then provide some boilerplate JS code to bootstrap your own custom generator engine. It all uses Handlebars.js internally so it’s pretty robust and quick to work with. A number of us are working on SDK generators for java, ruby, python, .net, go and others (JS is already covered by the raml-client-generator project). There are server side options for JAX-RS, python, etc as well as automated test code… in the works using the same generator, and with a little work a Markdown or HTML generator could be written for help generation. In short, especially if you are looking for client side SDKs and possibly server side, you can use RAML as your single source of truth to produce the full gamut of client and server output.
@justjacksonn that sounds really interesting, thanks for the heads up. When you have something concrete, please consider getting in touch and writing about it, or just talking to me about it in depth and I’ll do the writeup if you don’t feel like it - I’d love to explore these concepts in a bit more depth.
Likewise, as the author of the article above I find it very interesting. When I looked at RAML for the first time, it felt like there were all sorts of possibilities for code generation, mocking, testing against and so on - so it’s great to know they’re being explored.