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.