this seems like another version, but with a different website…
personally, i found the swagger ui a bit difficult to navigate at times.
Hey… have you tried to read an API defined by swagger? Is very hard to read, and I think that is one of the biggest limitations that Swagger has.
In RAML, specifically, yaml markup was choosen to provide a human readable API definition. In addition, there is plenty of yaml parsers for different languages out there, which make raml parsers creation easier.
Yeah, there are a lot of API specification formats on the scene now. I’ve also been looking at API-Blueprint a lot. I think each competing format needs to be evaluated on these points (at least):
- Can the format provide useful documentation to your API’s users?
- does it have goot renderable output?
- Does it provide facilities for showing examples as well as definitive format specifications (schemas)
- Does the format describe the API in such a way that it can be auto-validated from both the server and client end?
- e.g., can your client know definitively that it is sending correctly-formatted data?
- can your server know definitively that it is responding with data that fits the specification (both the endpoints and the input/output data formats)
- Can clients for many languages be auto-generated from the format?
- Is there documentation generation that puts things in terms of the client library instead of the HTTP API?
- Are the clients actually nice to use?
A lot of these points are about tooling around the formats (doc generators, server-side integration with web frameworks, client generators), but the format itself affects a lot. For example, if the format only has support for examples and not schemas, then you can’t do very good data validation. One of my beefs with a lot of these formats is that, as far as I know, none of them provide good hints for generating convenient client APIs. e.g., it would be a lot nicer if I could say client.create_foo() instead of client.foo().post() – the HTTPness is very evident. These examples get a lot nastier and less intuitive in more complex cases, especially if an API isn’t very RESTy, but still not very nice even if it is.
Unfortunately I can’t speak much to the point of Swagger vs RAML, but I want to inform the discussion by laying out what I think are the interesting points of comparison.
Swagger improved in many ways on WADL, and we (the RAML workgroup) certainly owe a great deal to Tony Tam and the swagger team at Wordnik/Reverb for blazing important paths in this field. We seriously started down the road of adopting swagger for our own initiatives at MuleSoft.
But swagger, based on JSON, is severely limited by that format’s limitations, popular as it is for data serialization: it’s just too “crufty” with its required quotes and brackets, with its lack of indirection, and generally with its severely limited constructs. Basing RAML on YAML gave us all its human-readability and human-writability advantages, in particular the clear tree structure based on the indentations you’d want in your file anyway, and a lot of similar sensible conventions. It allowed expressing the API simply and intuitively by typing it out; we didn’t know many people who would type our their API in swagger, and indeed people didn’t treat their swagger files as the source code for their APIs. We believe that emphasizing the source code of the API itself (not its implementation) encourages a design-oriented approach to APIs. The interface, the contract between the provider and the consumer, is exposed directly with minimal cruft: if it’s clean and clear and consistent, that’s evident, and if it’s not, well that’s evident too.
Further, and critically, RAML allows capturing API patterns in externalizable resource types and traits. Not only can this drastically improve the readability and writability of the API, but it encourages and rewards pattern reuse within and across APIs. We believe consistent APIs speed up development of client apps and increase their reliability; more broadly, as the number of APIs explodes, we’re hopeful that providers begin to converge on a small number of best-practice patterns.
Ultimately, we’re hoping that a de facto standard emerges, because it’s good for the entire industry. An important reason for developing RAML was to find something that would be so appealing to developers that broad adoption would follow, much as REST has flourished because of its simplicity and developer appeal.
A very key differentiation is that RAML is a “modelling language” not a “description language”, this might seem minimal but it’s not:
RAML is designed primarily for api-first development (or api modelling) and thats why readability and patterns are so important. Swagger (and others) on the other hand are more about describing an (existing) API in order to allow a interactive console or client to be generated.
Designing/modelling your API for your users (APX) is very important in creating a great API for your users, rather than generating something from maybe jax-rs classes or something.
I think a key missing point to these API format discussions is that the underlying format doesn’t really matter (for the most part). It’s the tooling to build the APIs that is most important. With swagger to RAML, swagger to WADL, RAML to WADL, anything to Postman and back again converters, it seems that it’s clear that all these formats are in some way compatible with one another. If I have a tool like Postman that makes it very easy to build a REST request, and can export/save that request in any of the other formats, then I don’t necessarily need to be concerned with the JSON or whatever format the API is stored in. I like to build my APIs using Postman, it is very easy and fast, and I can quickly test my APIs right in the UI. The one thing lacking (for now…it’s in the works) is documentation generation. Therefore, if I want swagger UI, I can export the Postman JSON, convert it to swagger, and have it show up in the Swagger UI.
My previous experience with Swagger and RAML
I can compare Swagger to RAML based on following knowledge and experience:
Swagger: authored and reviewed API declarations in Swagger (v1.1 and later v1.2) for couple of services, filed bunch of issues, wrote internal library for testing APIs declared by Swagger, implemented own Python based web service declaring API using Swagger.
RAML: discovered a week ago and studied the specification and tutorials. Her I lack more practical experience.
Here are my observations:
- look nice
- code generation (servers side and client side) seems to be of high priority
- limited support of JSON Schema, no support of XML schemas
- provide some documentation of used format
- keep the YAML based spec of API simple, readable, and in the center of focus
- document the format carefully
- support JSON and W3C XML schemas
- provide tooling for documenting and testing
Specification of the format
I consider specification of the format the most important feature, being even more important than most of the tooling.
- specification exists
- in many cases referencing (to versions, draft/release) is not clear
- hard to read, it is rather long
- specification exists
- carefully written, references are clear
- very easy to read
Support for schemas
I like schemas as form of “electronic form of contract on data structures”.
And I expect any REST specification framework to support at least JSON Schema (latest draft) and W3C XML Schema. Other schemas are welcome too (I like RELAX NG compact syntax - it is hard to beet it’s readability).
Schemas in Swagger
- real support for subset of JSON Schemas. WARNING: In practice I have found, supporting subset of
JSON Schemas means no real support for schemas. Swagger 1.2 uses only subset of JSON Schema
constructs and 2.0 reads about the same (listing supported constructs). In many cases is valid JSON Schema not usable and must be modified.
- no support for XML Schemas. I understood, there can be some canonical form of XML depicting what is possible for JSON. Did not use that.
Schemas in RAML
As simple as:
- JSON Schema supported (in 0.8 bound to Draft 3, in 1.0 plans to support any referenced schema version)
- XML: W3C XML schema supported.
As daily user of vim editor, I do not like being limited by features present or missing in some IDE. Important features and related things comes first and bring great value and it takes time to get them in tooling and I do not want to wait, sometime for ever.
So my expectations to tooling is rather minimal:
- evaluate, that authored spec is valid
- if possible, render readable spec of my API, ideally allow testing it
All the rest (generation of server or client side code) does not seem to be so crucial to me.
- Swagger UI is simply nice. And it allows testing the API.
- Server side code generation - not interested. Implementing server side shall be easy without tooling. And I expect the code to be generated once and modified (being detached from original generation tool) many times.
- client side code generation - not interested much. REST clients shall be easy to author. I do not
expect complex stuff being well resolved in auto-generated client code.
- editor for Swagger 2.0 looks very nice and promising (but not completed at the moment)
- missing tools for evaluating correct Swagger API declaration.
(I am missing longer practical experience here, so problems are likely to be found too here)
- editor - exists and looks nice. Missing practical experience
- generated specification of API - looks nice.
- notebook - great bonus with very smart serialization format (markdown)
- validator - such a tool exists
- looks nice at first, but brings unpleasant surprises
- pays high penalty for focusing on code generation and nice looking Swagger UI, crucifying
siplicity and general schema support
- the format is too complex while being limited
- suffers from lower level of care for Swagger format specification.
- even Swagger 2.0 suffers from all the above problems
- looks simple
- very readable
- API spec code centric
- support for JSON Schema and W3C XML Schema
- support consistent API by patterns
- high quality spec of the RAML format itself
- surprises by date time format used as data type based on RFC2616 (the only negative surprise so
far, I would expect RFC3339 nowadays.)
For me is RAML clear winner.
Swagger pioneered this area, but I feel, the priorities it is build on are a bit odd (nice Swagger
UI crucifying simplicity and general schema support). Even Swagger 2.0 shows these problems and it
is hard to imagine, future versions would improve the situation in this direction.
RAML is younger, learnt a lot from it’s predecessor and is well crafted.
For RAML 1.0 I would wish to keep current priorities and possibly provide even more generic
support for schemas of more types.
@vlcinsky, have you looked at the Swagger Editor, which claims to support YAML file input.
With that, are you still confident that your claim of “limited support of JSON Schema” and “Swagger 1.2 uses only subset of JSON Schema constructs and 2.0 reads about the same” are still relevant?
If RAML’s strength is about YAML format based readability, then the support for YAML input by Swagger 2.0 Editor may have already addressed the problems that you guys raised. Please take a look.
@toddwalden, have you looked at the Swagger Editor, which claims to support YAML file input.
If RAML’s strength is about YAML format based readability, then the support for YAML input by Swagger 2.0 Editor may have already addressed the problem.
YAML is nice, but not the most important feature.
The core question is: What APIs can I describe by given method?
- Swagger: Data types are limited to JSON, namely subset of constructs offered by JSON Schema Draft 4.
- RAML: For JSON complete JSON Schema is supported, for XML, complete XML Schema is supported.
I consider this to be very big difference. With RAML I can feel free to design content of my payload in any of supported schemas and be sure, I could make it part of valid API specification.
With Swagger, the payload designer must follow restrictions (supported JSON Schema subset) and for XML only canonical representation supported by JSON is possible to describe. If you cannot follow that, one cannot include enough details about data structure in the API spec.
Swagger still supports only subset of JSON Schema: see Swagger 2.0 spec, section Data Types which claims:
Primitive data types in the Swagger Specification are based on the types supported by the JSON-Schema Draft 4. Models are described using the Schema Object which is a subset of JSON Schema Draft 4.
The word “subset” is still there.
The Schema object section tell us:
The Schema Object allows the definition of input and output data types.
These types can be objects, but also primitives and arrays. This object
is based on the JSON Schema Specification Draft 4
and uses a predefined subset of it. On top of this subset, there are
extensions provided by this specification to allow for more complete
OK, there is some support for extensions - but do not ask me to go through an excercise to describe description of a payload using standard XML or JSON schema by means of Swagger. With RAML - this is just as easy as it should.
Conclusion: The conceptual differences between Swagger and RAML did not change by Swagger 2.0 despite of much improved support for YAML (restrictions on supported data types and schemas are stil there).
Personally I would say Swagger has much more scopes in designing the API.
RAML on other hand is easy to use and much more flexible and supports high quality specification, but somehow I feel it needs to come with lot more features like Swagger, which I am sure it’s getting better.
RAML has an advantage as it is relatively new compared to Swagger and there is much more scope of improvement than Swagger
@anir37 seeing you all other the forum, welcome can you elaborate a little bit more on “has much more scopes” or " a lot more features"? any example would help immensely to improve RAML.
I too would be very interested in you elaborating around what features swagger has that raml is missing.