4 ms·

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?

bpicolo 10y ago
Write swagger in yaml and it's just as pleasant.
- xiaoma 10y ago
  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://raml.org/developers/raml-200-tutorial#traits
  - pbowyer 10y ago
    http://stoplight.io/ 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.
curun1r 10y ago
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.
xiaoma 10y ago
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.
lomnakkus 10y ago
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.)

bpicolo 10y ago

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

xiaoma 10y ago
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://raml.org/developers/raml-200-tutorial#traits
- pbowyer 10y ago
  http://stoplight.io/ 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.

curun1r 10y ago

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.

xiaoma 10y ago

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.

lomnakkus 10y ago

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