OpenAPI and RAML in comparison

APIs are the digital glue that connect our modern IT systems and require proper documentation. Big companies often struggle with creation and management of their APIs. Due to a lack of documentation design flaws appear too late to get fixed at moderate cost.

An adequate documentation is also key for API maintenance to establish a common understanding of current and future features among all stakeholders. Documenting existing APIs should also be simple and allow inclusion of payload fragments and examples. Considering agile projects and API-first approaches that undergo constant changes, the API itself should preferably adopt automatically.
We thus compare current RESTful modelling specifications to tackle these challenges.

Narrowing down the current specifications on the market based on features, share, surrounding ecosystem and their community only OpenAPI Specification and RAML (RESTful API Modeling Language) remained.

Hands-on experience

Given the extensive communities of both specifications, we documented an interface in OpenAPI as well as RAML to get hands on experience. We used their development tools, a web application named swagger-ui for OpenAPI and API Workbench for RAML, which is an IDE running as plugin in Atom editor. Both tools check the human readable YAML code immediately and indicate syntactic errors. We slightly preferred RAMLs API-Workbench over swagger-ui, though the usability was quite similar.

The elements and document structure of both approaches looked also very much the same. Anyhow we were a bit in favor of RAML due some additional elements that allowed to model more distinct. Finally, we tried to include existing XML schema files of our sample API into our documentation. In RAML it has been a matter of seconds, while it was impossible using OpenAPI. Modelling the payload of our requests in OpenAPI has only been possible with JSON Schema. Converting existing XSD is rather difficult and thus this use case is rather not a good fit for OpenAPI, which relies on pure JSON. Additionally, inclusions were also not supported the same way as in RAML. RAML allows to include any file content (e.g. code fragments) in its documentation, while OpenAPI only supports references to child elements stored in external JSON or YAML files.
After conducting our own experience on our use-case, we summed up our findings and listed the pros and cons of both approaches.


OpenAPI as well as RAML have very much in common. Projects relying on the extensive language support and tool integrations will tend to OpenAPI. But if the language support is not crucial as implementations are foremost done in standard languages such as Java, RAML is an equivalent option. In our demo use case we opted for RAML due to its support of code reuse and inclusions of existing code fragments. We had to document existing interfaces with XSD payloads, which would have caused additional efforts by modeling in OpenAPI JSON Schema. OpenAPI and RAML both have a large community and are backed by market leaders, so you will never be wrong choosing one of them for API documentation.


Author: Peter Brinkhoff

Read now

Blog - Technology & Innovation

GraphQL: An alternative to RESTful services

Read now

More News


With Q_PERIOR, you have a strong partner at your side.
We look forward to your challenge!

2018-07-24T09:32:05+00:0018. May 2018|

Cookie Settings

In order to guaranty the functionality of our website, cookies are indispensable. Furthermore, we use cookies to improve your user experience, to analyze and optimize website functionalities and to provide content, which is matching your interests.

Please select an option to continue.

Data Protection | Imprint

Please select an option to continue

Your selection has been saved successfully.

Further Information


To continue, please select a cookie option. Here you can find information about the options and their meaning.

  • Accept all cookies:
    We use Google Analytics to create user statistics and to improve our website. Furthermore, we use Youtube to provide you video content.Furthermore we embed YouTube videos on our website. When activating the play button YouTube sets a Cookie.
  • Only accept necessary cookies:
    We do not use Google Analytics and YouTube and we will not set any cookies unless they are technically necessary. YouTube Videos are therefore blocked by default. In order to unblock YouTube videos in the future, please use the individual settings in every YouTube video.

You can change your cookie settings at any time here: Data Protection.