After a long search we decided to issue documentation in a format RAML. So it called specialized language to describe REST API. His possibilities and advantages will be discussed in this article.
Why RAML
How should document the API? This question is not as simple as it might seem at first glance. The first and easiest option that comes to mind - provide a description of the API in the form of a plain text document. So do many people (including very well-known companies). We are not just used that way.
For all its simplicity, it has the following disadvantages:
Text documentation is difficult to keep up to date;
Often verbal API descriptions are not sufficiently descriptive;
The scope of the use of "verbal" Documentation is very limited (for example, based on it cannot generate an interactive test page).
To simplify the process of documentation, you can use specialized tools and services. As a rule, they generate documentation based on the description in a standardized format - usually JSON or Markdown.
None of these formats for writing documentation is not appropriate. JSON was originally created for exchanging data on the Web. When using it for other purposes will inevitably have to resort to "crutches" - for example, custom fields, beginning with the $ sign. In addition, make descriptions in JSON manually - it is quite routine and tedious (especially when it comes to descriptions large).
In the above-described difficulty paying attention, many users of the popular tool Swagger. Soon Swagger developers decided to simplify the job of writing specifications and created a corporate editor with support for YAML.
Of course, YAML is much more convenient than JSON. But its use is associated with certain difficulties. The fact that there are descriptions of the API always repetitive elements (e.g., the circuit response, which may be the same for different types of HTTP-requests) that have each time to register manually. Now, if they can be had once and for all to register in a separate file and refer to it in the case nebhodimo.... But, alas, is that this is not possible.
As for the format Markdown (used, for example, in the API BluePrint), it is intended primarily for processing text, not to be used as a basis to generate. Adapt it under the API documentation is very difficult. For the same reason, have not led to any noticeable results Establish an attempt to describe the format of the API on the basis of XML - for example, language WADL (Web Application Description Language), developed by Sun Microsystems back in 2009, but has not been widely disseminated.
Founders of the project RAML (the acronym means REST-Full API Modeling Language - a language for modeling REST API) attempted to develop a language intended solely to describe the API and fix flaws inherent in other formats. The first version of the specification RAML was published in 2013. The main developer is the company RAML MuleSoft; the project also attended by representatives of such companies as Cisco, PayPal, VoxInc and others.
RAML undoubted advantages are:
Simple and logical syntax, based on the format YAML;
Support inheritance and the ability to connect external file specifications.
An additional advantage is the presence of a large number of converters, parsers and generators online documentation. Some of them are described later, but for now let's move to the Review features syntax RAML.
