How is this different from swagger?


#1

this seems like another version, but with a different website…


#2

personally, i found the swagger ui a bit difficult to navigate at times.


#3

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.


#4

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? :slight_smile:

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.


#5

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.


#6

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.


#7

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.

So what we really should be focussing on is the tools that make it easy to build robust APIs. Right now for me, that tool is Postman. It’s the only tool I’ve found that allows me to design my APIs by simply constructing a request the same way I do in any other REST tool… punch in the URL, headers, auth, and then test it. But it also has built in workflow capabilities, such as adding JavaScript processing to build chainable requests without having to copy/paste response body/headers to then use in a subsequent request. Sharing collections of these requests with team members is super easy, and anyone on my team can quickly use the same collection I built to run sanity tests, see if an API works, etc. When everyone is happy, we publish the same collection to the web for our customers to use. Now anyone can use the same collection we use internally, which results in a great bit of reusability and possibly even additions from the community that we didn’t think of, that we can fold back in to our own collection(s). With documentation already part of Postman, but more additions coming soon, generating SDKs, documentation, etc is not too difficult, although then to be fair, it does require the knowledge of the file format. :slight_smile:


#8

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:

General concept

Swagger concept

  • 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

RAML concept

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

Swagger spec

  • specification exists
  • in many cases referencing (to versions, draft/release) is not clear
  • hard to read, it is rather long

RAML spec

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

Compare tooling

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 tooling

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

RAML tooling

(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

Conclusion

Swagger

  • 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

RAML

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

Winner? RAML

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.


#9

Very nice drill-down @vlcinsky. Thanks!


#10

Thanks @vlcinsky for this comprehensive overview.


#11

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


#12

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


#13

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

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


#14

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


#15

@anir37 seeing you all other the forum, welcome :wink: 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.


#16

I too would be very interested in you elaborating around what features swagger has that raml is missing.