

SOA Series Part 3: Documenting and Generating Your APIs - tvalent2
https://techblog.livingsocial.com/blog/2014/06/26/soa-series-part-3-documenting-and-generating-your-apis/

======
cmain
Good article. I was recently surprised to find that DreamFactory
([http://dreamfactory.com/](http://dreamfactory.com/)) is also using Swagger.
Only word of caution I have to JS folks is that the swagger-js implementation
for client resource generation is in need of some serious cleanup. Luckily,
DreamFactory has done some of this in an Angular module and made it open
source: [https://github.com/dreamfactorysoftware/angular-
dreamfactory...](https://github.com/dreamfactorysoftware/angular-
dreamfactory/blob/master/angular-dreamfactory.js)

Overall though, working the past few months with Swagger has been a good
experience.

~~~
curun1r
I've had the opposite experience trying to work with Swagger in a dynamic
server-side language (node). It's just a major pain to work with and the node
implementation has many obvious bugs that are being ignored by the developer.
Swagger, to me, only seems to be a good option when most of the meta data is
coming from static analysis. It works well in languages like Java, but not so
much in languages that are less syntactically strict. And since it's not
really designed to be written by a human, you're stuck having to use some hack
(either of your own design or the poor 3rd-party options currently available)
to generate the Swagger json.

I've been much happier with
[http://apiblueprint.org/](http://apiblueprint.org/) and it's approach of
making the executable documentation writable by developers.

~~~
cmain
Ah, we are using Java and using the Swagger jax-rs implementation as well.
Good point though, not too surprised the Node implementation is lackluster.

