Hacker News Reader

Comment by tscherno | Hacker News Reader

After writing a lot of long swagger specs I tried RAML which although not that widely supported feels much more pleasant to write. Any toughts?

View on HN

Add API Blueprint to the list of more pleasant to write alternatives. Not to mention it's much easier to render into human-readable documentation. I too have been somewhat dismayed by the rise in popularity of Swagger when there are two competing solutions that, to my mind, are superior.

Has the tooling for RAML improved esp. around the licensing? Last time I looked, the 'standard' server implementation on the JVM had rather restrictive licensing, IIRC it was dual-license AGPL or a commercial license?

(AFAICT RAML is actually a much nicer spec, both simpler in some ways and more powerful in others, but as I say I was never actually able to use it due to the licensing issues on implementations -- only read it.)

Yes, RAML is great. I find it a lot more concise and don't see any advantage to using Swagger, despite that it's older and more widely used.

Write swagger in yaml and it's just as pleasant.

How so? At least in my experience, Swagger doesn't have anything equivalent to traits so there's no way to DRY out your docs. If you have 50 endpoints with pagination, you have to document how that works 50 times. If you change how pagination queries are structured, then you have to change your docs in 50 places. With RAML, you would just change the trait and then all of your docs and your automated testing against them will be updated.

Swagger does have $ref, but it's a much weaker abstraction than RAML traits and resourceTypes.

http://raml.org/developers/raml-200-tutorial#traits

http://stoplight.io/ lets you use traits in Swagger. I've really enjoyed using a visual tool to build the API definition, though I don't find it helps with writing documentation.

Reply on news.ycombinator.com