I've been looking for automatic creating the documentation for the REST API of a project I'm working on. First, Hydra (http://www.hydra-cg.com) shows up with an interesting idea for designing Web APIs. Later some colleagues recommend me to use Swagger 2.0 (http://swagger.io) as code generator. Then, I realise that both specifications can solve the same problem of documenting the REST API.
What are the downsides/benefits of using Hydra or Swagger specification?
Thanks!!!
Swagger is well established and supports a wide range of languages and frameworks. It doesn't force you to write the API in a specific style and it should be a better fit if you just want to document an existing API.
Hydra looks like interesting framework to develop REST APIs but has yet to be adopted by any standards organizations and the industry to make it a real standard. It's just an unofficial draft by a W3C community group for now. It also seems very new and provides experimental tools for some languages, which don't seem ready for production. I'm not even sure if you can integrate the framework with an existing API without changing the API significantly.
As stated by inf3erno, Hydra is more focused on the original definition of REST services and generated documentation is just a byproduct. On a first glance it seems to me that they are using principles similar to HATEOAS and try to formalize that technique using vocabularies. I think there is good reason to stay with the more simple modern definition of REST services though and don't make development to complicated by adding HATEOAS or vocabularies.