SOA Series Part 3: Documenting and Generating Your APIs

https://techblog.livingsocial.com/blog/2014/06/26/soa-series-part-3-documenting-and-generating-your-apis/

by tvalent2 • 12 years ago

22 3 12 years ago

techblog.livingsocial.com

cmain2• 12 years ago

Good article. I was recently surprised to find that DreamFactory (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...

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

curun1r• 12 years ago

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/ and it's approach of making the executable documentation writable by developers.

cmain2• 12 years ago

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.

SOA Series Part 3: Documenting and Generating Your APIs

Related Stories