Goa: Design-First API Generation
goa.design
goa.design
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.
This looks like a good 'toolkit' to ease the development of such a service. There are also some code examples, e.g. to implement authorization with JWT or OAuth2: https://github.com/goadesign/examples/tree/master/security
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?
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.
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]
[1] http://swagger.io/open-source-integrations/ [2] http://swagger.io/getting-started/
For C#, please try https://github.com/domaindrivendev/Swashbuckle
For PHP, please try https://github.com/zircote/swagger-php
For other langauges, just do a google search on "{lang} swagger" and you will probably find something useful.
- 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 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)
[1] https://github.com/swagger-api/swagger-codegen/pulls?utf8=%E...