I get the impression that these are code generating tools built from a specification file.
I have real world experience with two tools which fit that rough description. SOAP and google app-engine end-points.
I would unambiguously describe both as awful. Really horrible experiences with both. They tie your systems to large, and difficult to understand tool sets. SOAP wasn't obviously buggy, but app engine endpoints are unpredictable and the generated code produces some serious awkwardness.
I don't want to slap a label on these tools and dismiss them off-hand.
We've tried various ad-hoc approaches to documenting our APIs in the past.
When we switched to RAML (and json schema) for our API definitions, everything got a lot better.
RAML defines the resources (uris, parameters, media types, etc.) while json schema is used for more detailed information (what's the exact structure of the application/json response to a call to GET /jobs).
While there are theoretical gains in generating code from the RAML, we don't seek these out as its no big deal to hand-code Spring controllers, even a lot of them.
The real value for us is in having a single, well-documented source of truth about our APIs. Customers using the APIs, developers implementing them, testers testing them, trainers learning about them, all go to one place.
And RAML has some handy tools (like raml2html) to create human-readable documentation from the RAML.
We've also added our own tools to parse sample json responses against the json schema which have greatly aided us in finding discrepancies.
In short something like RAML (or probably blueprint or swagger too) is, I feel, essential if you have a lot of APIs and a lot of people, and if you have aspirations of an increasingly automated toolchain.
FWIW, there's a line of thought that RAML is at odds with hypermedia and HATEOAS. After all, why would anyone need a detailed API document, when clients should be getting information from the hypermedia responses of previous API calls? I don't agree with that, even if just because internally your development team still needs to build out all those APIs.
I've worked with API Blueprint as it seems to have the widest support across API tooling providers, along with a sane syntax. It's really nice to be able to spec out a blueprint and then simulate an API [1]. Also being able to run tests on the real API, but based on the API docs which describe expected behavior, has exposed many bugs [2].
I just recently watched the "Microservices Summit" from microservices.com/Datawire [3], and the most-repeated lesson from Netflix, Amazon, and Yelp was to design API-first, not data-first. As engineers we tend to design an API around our data -- but developers have to interact primarily with the API, and then with the data. With API spec tools we can quickly fake an API and try to interact with it, then find out what sucks and rewrite it, all before sinking time into the actual implementation. SendGrid does this, and their API has been a breeze to work with [4].
The last step is to use a client SDK generator like Apimatic [5] -- but that only works if the API actually conforms to the docs. It's probably difficult to get an entrenched codebase to switch to spec, but for any new API I wouldn't do it any other way.
I've used RAML for the past six months, but only to generate documentation. It's pretty easy to learn. A RAML file is a lot cheaper to rewrite, so I write RAML first and figure out if the endpoint makes sense before I write the backend code manually.
I don't know of projects generating the actual server side code from RAML/Swagger/API Blueprint other than the OPs project.
Other than documentation, they are useful for generating mock servers for testing, API client libraries, and collections for postman/paw.
RAML and the others have a lot of value simply as the source of truth for your API definitions. You need to hold that somewhere - and probably share it with others - and a DSL specifically designed for documenting APIs is a good place. Where else would you hold it after all?
However, as developers we love to reach for the stars, so surely that's not enough? Surely we should be able to generate complete, working systems from the RAML (or whatever)! I would say that's a pipe-dream, just as it always has been, and just as it always will be. You might be able to generate a few stubs from RAML (or a UML diagram), but annoyingly, those are also the easiest things for a developer to just crank out anyway, and you'll be up to your ears in compiler soon enough.
The projects you listed above are just spec formats that describe APIs. In the case of RAML there are companies out there including MuleSoft that are building generators and other kinds of services around it. I believe the same goes for Swagger and the others.
The one shortcoming of these approaches is that they are well-suited for local APIs but less so for network APIs, especially as you start to wire them together. For example, with network APIs you need to worry about stuff like rate limiting, and there's no way to express them.
That said, if you're trying to document a bunch of REST APIs, it's a very helpful thing to do. Just not a total solution :)
I had a look at the websites for each of the three tools the article specifically mentions
I get the impression that these are code generating tools built from a specification file.I have real world experience with two tools which fit that rough description. SOAP and google app-engine end-points.
I would unambiguously describe both as awful. Really horrible experiences with both. They tie your systems to large, and difficult to understand tool sets. SOAP wasn't obviously buggy, but app engine endpoints are unpredictable and the generated code produces some serious awkwardness.
I don't want to slap a label on these tools and dismiss them off-hand.
Anyone used them 'for the win'?