Swagger (now OAS) and RAML are two of the most popular specifications for developing APIs on the market right now. But which one is better for your business? What is the difference between them?
What is Swagger (OAS)?
Swagger—recently renamed to Open API** or OAS—is a type of framework that was designed to describe, produce, visualize, and consume RESTful web services. Referred to "language-agnostic," it has been developed to be read using a common language. Readme.io produced a perfect example that can be used to help understand exactly what Swagger is:
Think of it as a blueprint for a house. You can use whatever building materials you like, but you can't step outside the parameters of the blueprint.
Swagger's popularity stems from its simplicity. From its concise documentation to its to its ease of readability for machines and humans alike, Swagger is a framework that has been made very easy to utilize.
**For the purpose of this article, we will continue to refer to the language as Swagger, as that is what it is still regularly referred to in the industry.
Pros & Cons of Swagger
Pros of Swagger/OAS
A large community and support-base
High adoption rate, meaning lots of documentation
Strong framework support
Has the largest language support of any opensource framework
Cons of Swagger/OAS
Requires multiple specifications for some tools, including dev and QA
Doesn't allow for code reuse, includes, or extensions
Lacks strong developer tools
Requires schemas for all responses
What is RAML?
RAML, or RESTful API Modeling Language, is a YAML-based language for describing RESTful APIs. As the name implies, it provides all the information necessary to describe RESTful or practically-RESTful APIs.
According to a blog post on Nordic APIs by Kristopher Sandoval, RAML is very much a hierarchical style format, which is one of the many reasons it is such an excellent planning tool. By visualizing the cause and effect of requests to the API, as well as documenting specific examples of what return can be expected, APIs can either be documented or planned with incredible granularity."
Pros & Cons of RAML
Pros of RAML
Single specification to maintain
Strong, visual-based IDE and online tooling with collaboration focus
Allows for design patterns
Easy to get started
Cons of RAML
Lacks strong documentation and tutorials outside of specification
Limited code reuse/extensions
Muletiple specifications required for several tools, including dev and QA
Poor tooling support for newer versions
Swagger vs. RAML: Language Support
In comparison to one another, both Swagger and RAML are very capable, compatible with many languages.
Swagger's additional capabilities: Clojure, Coldfusion, D, Eiffel, Erlang, Groovy, and Typescript
RAML's additional capabilities: Elixer and Pearl
Both languages are strong and able to produce excellent APIs despite their differences. Their key differences are what can help you determine which is best for your business.
Swagger's best features are its strong documentation and compatibility with lesser used languages. It provides a fast setup and a large support community. The big takeaway for Swagger is that it is designed as a bottom-up specification. Swagger specifies the behavior which affects the API to create more complex, interlocking systems.
RAML excels at supporting the entire API's lifecycle. It provides a balance between developer tooling and technical writers without taking away from one or the other. It also is the fastest framework to ramp up your project. The main difference between the two is that RAML is a top-down specification, meaning it breaks down the system and explains the behavior of the various sub-components.source : https://blog.vsoftconsulting.com/blog/is-raml-or-swagger-better-for-building-apis