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.
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