SOA Series Part 3: Documenting and Generating Your APIs
techblog.livingsocial.com
SOA Series Part 3: Documenting and Generating Your APIs
1–4 of 4 posts
Re: SOA Series Part 3: Documenting and Generating Your APIs
#2Good 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.
Re: SOA Series Part 3: Documenting and Generating Your APIs
#3Good 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... Over…
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.
Re: SOA Series Part 3: Documenting and Generating Your APIs
#4Good 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... Over…
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 syn…
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.