Writing API documentation with RAML

The convenience of working with any API depends largely on how its documentation is written and framed. Now we are working on the standardization and unification of descriptions of all our APIs, and documentation issues are especially relevant for us.
After a long search, we decided to issue documentation in the RAML format. This is the name of a specialized language for describing REST API. We will describe its capabilities and benefits in this article.

Why raml

How do I document the API? This question is not as simple as it may seem at first glance.
The first and easiest option that comes to mind is to provide a description to the API in the form of a plain text document. So many people do (including very well-known companies). We also used this method more than once. For all its simplicity, it has the following disadvantages:

• textual documentation is difficult to keep up to date;
• often the verbal descriptions of the API are not clear enough;
• the scope of the use of “verbal” documentation is very limited (for example, an interactive test page cannot be generated on its basis).

To simplify the documentation process, you can use specialized tools and services. As a rule, they generate documentation based on the description in some standardized format - usually JSON or Markdown.
')
None of these formats is suitable for writing documentation. JSON was originally created for data exchange on the web. When using it for other purposes, it is necessary to resort to the help of “crutches” - for example, custom fields starting with the $ sign. In addition, compiling descriptions in JSON format manually is quite routine and tedious (especially when it comes to descriptions of large size).

Many users of the popular Swagger tool paid attention to the difficulties described above. Soon, Swagger developers decided to simplify the work of writing specifications and created a proprietary editor with support for the YAML format.

Of course, YAML is much more convenient than JSON. But its use is associated with certain difficulties. The fact is that in API descriptions there are always duplicate elements (for example, the response scheme, which may be the same for different types of HTTP requests), which you have to manually register each time. Now, if it were possible to register them once and for all in a separate file and refer to it if necessary ... But, alas, so far there is no such possibility.

As for the Markdown format (it is used, for example, in the BluePrint API ), it is intended primarily for the design of the text, and not for use as the basis for generation. Adapting it for API documentation is very difficult. For the same reason, attempts to create an XML-based API description format did not lead to any noticeable results — for example, the WADL (Web Application Desription Language) language developed by Sun Microsystems in 2009 but not widely used.

The creators of the RAML project (this abbreviation means RESTful API Modeling Language - the language for modeling the REST API) attempted to develop a language designed solely to describe the API and fix the flaws inherent in other formats. The first version of the RAML specification was published in 2013. The main developer of RAML is MuleSoft; Representatives of such well-known companies as Cisco, PayPal, oxInc also take part in the project. and others.

The undoubted advantages of RAML are:

• simple and logical syntax based on the YAML format;
• support for inheritance and the ability to connect external specification files.

An additional advantage is the presence of a large number of converters, parsers and online documentation generators. We will tell about some of them below, but for now let's move on to a review of the features of RAML syntax.

A brief introduction to RAML

Document structure

The RAML specification file consists of the following structural elements:

• introductory part ("cap");
• security scheme;
• profile description;
• description of objects and methods;
• description of the answers.

Consider these elements in more detail.

Prologue

Each RAML document begins with a preamble, which includes four essential elements:

• RAML version;
• document name;
• URI for which the API is available;
• API version described in the documentation.

It looks like this:

 #% RAML 0.8
 title: Example API
 baseUri: http://api.example.com/{version}
 version: v1

The prologue may also include various additional information — for example, information about the protocol used to communicate with the API:

 protocols: [http, https]

You can also prescribe the metadata of the documentation file:

 documentation
     - title: Home
         content: |
                   API Test Documentation

Security schemes

To start working with any API, you need to go through the authorization procedure. It can be done in different ways: through OAuth, using tokens, or using simple HTTP authentication. To describe this procedure in RAML, security schemes are used.
Consider as an example how authorization is described using the OAuth2 protocol:

 #% RAML 0.8
 title: Example API
 version: 1
 baseUri: https://api.example.com/{version}
 securedBy: [oauth_2_0]
 securitySchemes:
     - oauth_2_0:
                type: OAuth 2.0
         describedBy:
             headers:
                 Authorization:
                          type: string
             queryParameters:
                 access_token:
                       type: string
             responses:
                 401:
                     description: |
                         Bad or expired token.                 
                  403:
                     description: |
                         Bad OAuth request 
         settings:
           authorizationUri: https://example.com/oauth/authorize         
           accessTokenUri: https://example.com/oauth/token
           authorizationGrants: [code, token]

The following fragment contains the following information:

• The type parameter indicates that the OAuth2 authorization is used in the API;
• It further states that authorization data can be passed either in the Authorization header or in the access_token query parameter;
• then follow the possible response codes and their descriptions;
• At the end of the section, the settings section contains the URL for authorization, the URL for receiving the token, as well as the parameters required for authentication (authorization grants).

For convenience, security schemes can be saved in separate .raml or .yml files, and then referred to them if necessary:

 #% RAML 0.8
 title: Example API
 version: 1
 baseUri: https://api.example.com/{version}
 securedBy: [oauth_2_0]
 securitySchemes:
     - oauth_2_0:! include oauth_2_0.yml

This helps speed up the documentation process, avoid unnecessary repetitions and make documentation less cumbersome.

You can read more about security schemes and get acquainted with specific examples here (Security section).

Objects and methods

The following lists the main objects and their paths, as well as the HTTP methods that are used with these objects:

 / document
  get:
  put:
  post:
   / {documentId}
    get:
    delete:

This example describes an API with which you can work with documents. We can download documents to the local machine (GET), modify existing documents (PUT) and upload new ones (POST). With each separate document ({documentId}) we can also perform the following operations: upload to a local machine (GET) and delete (DELETE).
HTTP headers used with a particular method are described using the headers property, for example:

 / documents
    get
      headers:
         X-Auth-Token:
         required: true

Pay attention to the required property: it indicates whether the header is required (true) or optional (false).
In the description of objects and methods can be used numerous additional parameters. Consider the following example:

 / document
       / {documentId}
               uriParameters:
                        id:
                         description: document identification number
                         type: string
                         pattern: ^ [a-zA-Z] {2} \ - [0-9a-zA-Z] {3} \ - \ d {2} \ - \ d {5} $

Here we indicate that each of the documents that can be accessed through the API has its own identification code as a string (type: string), and also describes the format of this code using regular expressions.

The description, type, and pattern properties can also be used in method descriptions, for example:

 / documents
    get:
         description: Retrieve a list of documents
    post:
          description: Add a new document
    body: 
           application / x-www-form-urlencoded
                  formParameters:  
                          id: 
                            description: document identification number
                            type: string
                            pattern: [a-zA-Z] {2} \ - [0-9a-zA-Z] {3} \ - \ d {2} \ - \ d {5} $
                          name:
                              description: the name of the document
                              type: string
                              required: true
                           author: 
                                 description: The name of the author
                                 type: string
                                  required: true

In the description of the POST method, we indicate the parameters that need to be passed in the request body to add a new document: ID, name and author name. Each of these parameters is a string (type: string). Note the required property: it indicates whether the parameter is required (true) or optional (false).

For each method, you can prescribe an individual security scheme:

 / documents
   get
       [securedBy: oauth_2_0]

Query parameters

For each method in the documentation, you can specify query-parameters that will be used in the query. For each query parameter, the following characteristics are indicated: name, type, description, and example:

  / document:
      get:
        queryParameters:
          author:
            displayName: Author
            type: string
            description: The author's full name
            example: Ivan Petrov
            required: false
          name:
            displayName: Document Name
            type: string
            description: The name of the document
            example: Delivery contract
            required: false
          signingDate:
            displayName: signingDate
            type: date 
            description: the date when the document was signed
            example: 2015-07-15
            required: false

Profiles

To avoid unnecessary repetitions in the descriptions, RAML uses profiles (traits), which are written in the introductory part of the document:

 #% RAML 0.8
 title: Example API
 baseUri: http://api.example.com/{version}
 version: v1

 traits:
  - searchable:
     queryParameters:
          author:
            displayName: Author
            type: string
            description: The author's full name
            example: Ivan Petrov
            required: false
          name:
            displayName: Document Name
            type: string
            description: The name of the document
            example: Delivery contract
            required: false
          signingDate:
            displayName: signingDate
            type: date 
            description: the date when the document was signed
            example: 2015-07-15
            required: false

In the future, the profile can be addressed when describing any methods:

 / document:
      get:
             is: [searchable]

More details about the profiles and the features of their use can be found in the official documentation (section Traits).

Description of the answer

In the description of the answer must indicate its code. Also in the description you can add a schema (schema) - an enumeration of the parameters in the response and their types. You can also give an example of a specific answer (example).

  / documents:
    / {documentId}:
      get:
        description: Retrieve document information
        responses:
          200:
           body:
            application / json:
              schema |
                {"$ schema": “http://json-schema.org/schema”,
                 "type": "object"
                 "description": "a document"
                 "properties": {
                      "id": {"type": "string"}
                      "name": {"type": "string"}
                      "author": {"type": "string"}
                      "signingDate": {"type": "date"}
                example: |
                {"data:" {
                   "id": "DOC3456"
                   "name": "New Delivery Contract"
                   "author": "Ivan Petrov"
                   "signingDate": "2015-05-20"
                 },
                 "success": true
                 "status": 200
               } 

You can save response schemes in separate .yml or .raml files and access them in other parts of the documentation:

 schemas:
  -! include document-schema.yaml

 / articles:
  get:
   responses:
    200:
     body:
      application / json:
       schema: document

Visualization and Generation of Documentation

RAML2HTML and other converters

Despite the fact that RAML is a relatively new format, a sufficient number of converters and parsers have already been developed for it. An example is ram2htmtl , which generates a static HTML page based on a RAML format description.
It is installed using the npm package manager:

 $ npm -ig raml2html

To convert a RAML file to HTML, just run a simple command:

 $ raml2html api.raml> index.html

The ability to create custom templates for HTML files is supported (for more details, see the documentation on GitHub at the link above).
Of the other converters, we also recommend to pay attention to RAML2Wiki and RAML2Swagger .

API Designer

Mulesoft company (one of the active participants of the RAML project) has created a special online tool with which you can simplify the work of writing documentation and subsequent testing of the API. It is called API Designer .
To start using it, you must first register on the site. After that, you can get to work. API designer provides, firstly, a convenient interactive editor for writing documentation online, and secondly - a platform for testing.
It looks like this:



Online documentation is automatically generated on the right side of the page. Here you can also test the API: to do this, simply expand the description of the desired request and click on the Try it button.

The API Designer also allows you to load RAML files from a local machine. Supported import of API description files for Swagger.
In addition, the API Designer stores statistics for test requests to the API.

API console

API console is a useful tool developed by MuleSoft. It can be used to generate API documentation directly in the browser. Specification files can be either downloaded from the local machine, or you can specify a link to an external source:



The API Console includes several sample files that represent descriptions of the API of popular web services: Twitter, Instagram, Box.Com, LinkedIn. We tried to generate on the basis of one of the bottom documentation - it looks quite nice:



The output documentation is interactive: it can not only read the API description, but also perform test queries.

Conclusion

In this article, we looked at the main features of RAML. Its undoubted advantages are simplicity and consistency. We hope that in the near future RAML will become even more widespread and will occupy a worthy place among the tools for documenting the API.
If you have questions, welcome to comments. We will also be happy if you share your own experience of using RAML in practice.

If for one reason or another you cannot leave comments here - welcome to our blog .