RAML

A competing specification, RAML, stands for RESTful API Modeling Language. It uses YAML for description and enables discovery, code reuse, and pattern-sharing.

The rationale behind establishing RAML was that while OpenAPI is a great tool to document existing APIs, it was not, at the time, the best way to design new APIs. Currently, the specification is being considered to become a part of the OpenAPI Initiative.

A RAML document may be converted to OpenAPI to make use of the available tooling.

Here's an example of an API documented with RAML:

#%RAML 1.0

title: Items API overview
version: 2.0.0

annotationTypes:
  oas-summary:
    type: string
    allowedTargets: Method

/item:
  get:
    displayName: getItem
    queryParameters:
      itemId:
        type: string
    responses:
      '200':
        body:
          application/json:
            example: |
              {
                "itemId": 8,
                "name", "Kürtőskalács",
    ...