This was/(is?) one of the goals of Swagger[0]. Lots of promises, but have yet to see it work in the wild. I want to use whatever Stripe uses for their API design.
Yes, Swagger is intended to be a service description in this space. But goa seems to allow you to do your design in their DSL and then generate a Swagger spec from it [1].
Todo: write a thing that makes Goa from a RailsAPI server. The goal is to have it be able to generate the same exact RailsAPI code. The usefulness is that a different team not as comfortable with Rails could use the generated Goa code to generate the same RailsAPI server in the language they're comfortable working with, make their contributions, and have that generate new Goa, which the first team would use to generate the updated RailsAPI code.
Kind of a Rosetta Stone for APIs, but only useful if it works both ways, picks up every small change in exacting detail, and works server ->spec ->same server. Not sure if that's even possible, but it'd be cool.
The creator of goa is presenting on code generation and APIs at Gophercon this year. I'm also presenting on goa at abstractions.io in August. I'm quite biased as a contributor, but I think goa is a great solution for APIs because it encourages you to think through the design completely and generates the code from that design. Generated code is idiomatic and clean. You can see me present at the Tampa Go Meetup here: https://www.youtube.com/watch?v=tCFrgWikEX8
I'm really happy to see this because I hear people talking about using Go to implement microservices, but fewer mentions of what tools they're using to implement them.
Both Swagger and Goa can generate API client code from their respective spec languages. Goa additionally has the ability to generate a Swagger spec from a Goa spec.
This makes me wonder why Goa just doesn't rely on the Swagger code generators? Are they not very good?
The Goa page talks about generating Swagger so you can use the Swagger doc generator. Maybe that's the only part of Swagger that the Goa developers think is useful?
Also, Swagger has more traction right now. Maybe the ability to generate a Swagger spec lets people not feel so locked in to Goa, the newcomer?
They approach the same problem from opposite directions. Goa's DSL will let you code a server, and then export a Swagger spec that clients can consume (and codegen their end from).
Whereas Swagger's code generators start with the Swagger spec already written. You can use them to generate a server, which will create the scaffolding but leave you with the logic to implement.
Would you mind linking to some docs on how to do that?
I only found this quote, which hints that it's a manual process (if your framework doesn't produce the spec):
"Either you create the definition manually (using the same Swagger Editor mentioned above), or if you are using one of the supported frameworks (JAX-RS, node.js, etc) [1], you can get the Swagger definition generated automatically for you." [2]
In my experience the swagger code generators are not very good (at least for go/node).
- Go - This thread on the PR adding go client generation is a good introduction - https://github.com/swagger-api/swagger-codegen/pull/1747, basically the generator currently only supports very simplistic datatypes and will just generate invalid code if you start to use any complex datatypes. The main user in that thread (casualjim) actually maintains (https://github.com/go-swagger/go-swagger) which is a much more robust implementation, but still has some rough edges such as:
- The generated servers don't give a nice (or even strongly typed) interface to implement. See an example of a handler here - https://github.com/go-swagger/go-swagger/blob/master/example.... First pass of Goa at least as a less leaky and more strongly typed implementation.
- All the actual codegen is done using gotemplates. As someone who has tried to make some small changes these are fairly hard to parse/understand (example: https://github.com/go-swagger/go-swagger/blob/master/generat...)
Overall the default swagger codegen is very simplistic and the alternative go-swagger code is better but has a few rough edges that are difficult to fix.
- Node - I haven't played around much with the node server generator, but the clients are very thing wrappers around the API without a ton of abstraction/client side safety/validation. Node JS obviously doesn't have types, but a good client library could still do runtime typechecking to make sure if I do createBook("hello") instead of createBook(new Book({})) the former would fail (instead of just sending it off to the server to deal with).
I recognize this may be a high bar for microservice codegen, but often swagger is compared to the likes of thrift, which has _very good_ codegen, and so these leaky abstractions and edgecases stick out in comparison. I can't yet speak to how Goa compares but the go server codegen seems better in the first pass.
For Go API client (lang: go), there are about 40 PRs (enhancements, bug fixes)[1] to Go API client since https://github.com/swagger-api/swagger-codegen/pull/1747 was merged into master. Please pull the latest master to give it another try and see if the Go API client meets your requirement.
For NodeJS server (lang: nodejs-server, renamed from nodejs), I agree it's not in its best form and there are still many rooms for improvement. If you've any feedback, please open a ticket via https://github.com/swagger-api/swagger-codegen/issues
For NodeJS client (lang: javascript), please give it a try as there may be confusion before that `nodejs` (deco) implies the NodeJS API client.
Disclaimer: I'm a top contributor to Swagger Codegen.
("lang" refers to the code generator name in Swagger Codegen)
I've been looking for the Google open source beta version of this. It's been killing me that I can't remember what it's called... I believe it's done in either C++ or Golang, green/white home page
[0] http://swagger.io/