[CookWithMe]

I wrote some RAML recently and found it very good for creating a machine-readable representation of an API. We also wanted to make it human-readable and use it as our API reference (with the API console). I found it to be mostly good, but had some trouble when explaining larger concepts that span several requests. Also, it's harder to point to the "important" parts of the API if it's sufficiently large than it was with our "freeform" reference.

I haven't looked into Swagger deeply, but RAML seems better at re-usability. Swagger seems to have way more traction though, and also more tools.

[pksunkara]

Can I suggest API Blueprint [1]? It is much more human friendly and easier to work on API design. Apiary has tools for complete API lifecycle management.

Disclaimer: I work on making API Blueprint better.

[1]: https://apiblueprint.org

[pavel_pt]

Ditto, used RAML on a previous project and everyone involved really enjoyed it. It manages to capture just enough about how thinks work without getting overbearing. I particularly like the fact that it allows for examples to be specified.

I haven't built anything with Swagger but I never clicked with it the way I instantly did with RAML. It's a pity - there seems to be a lot more industry and open source support behind Swagger than there is for RAML which is mostly backed by MuleSoft.

[earth2marsh]

Swagger added support for examples with version 2.0 of the format, see: https://github.com/swagger-api/swagger-spec/blob/master/vers...

[earth2marsh]

If you're interested in re-use in Swagger, see the guidelines here: https://github.com/swagger-api/swagger-spec/blob/master/guid...