
Goa: Design-First API Generation - kawera
http://goa.design/
======
nathancahill
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.

[0] [http://swagger.io/](http://swagger.io/)

~~~
niftich
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].

[1] [http://goa.design/design/swagger/](http://goa.design/design/swagger/)

~~~
nathancahill
We must go deeper.

~~~
seanp2k2
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.

~~~
nathancahill
Have you seen this? [https://github.com/mame/quine-
relay](https://github.com/mame/quine-relay)

------
bketelsen
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](https://www.youtube.com/watch?v=tCFrgWikEX8)

~~~
thinxer
How does this compares to gRPC which has many languages supported already?

~~~
bketelsen
gRPC is a great framework for generating RPC servers and clients, it's a
different space. goa is built for creating an entire REST API.

------
niftich
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.

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](https://github.com/goadesign/examples/tree/master/security)

------
cakoose
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?

~~~
niftich
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.

~~~
tokenizerrr
Swagger can also generate its spec from an already written server, and that's
how I'm using it primarily.

~~~
niftich
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]

[1] [http://swagger.io/open-source-integrations/](http://swagger.io/open-
source-integrations/) [2] [http://swagger.io/getting-
started/](http://swagger.io/getting-started/)

~~~
wing328hk
There are many plug-ins to to generate OpenAPI/Swagger spec from annotations
in the source code.

For C#, please try
[https://github.com/domaindrivendev/Swashbuckle](https://github.com/domaindrivendev/Swashbuckle)

For PHP, please try [https://github.com/zircote/swagger-
php](https://github.com/zircote/swagger-php)

For other langauges, just do a google search on "{lang} swagger" and you will
probably find something useful.

------
zghst
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

~~~
buckhx
GRPC? Not the same, but allows you to specify the API in a static file and
generate native language clients among many other things.

~~~
kawera
[http://www.grpc.io/](http://www.grpc.io/)

[https://github.com/grpc/grpc](https://github.com/grpc/grpc)

[https://developers.googleblog.com/2015/02/introducing-
grpc-n...](https://developers.googleblog.com/2015/02/introducing-grpc-new-
open-source-http2.html)

------
int_handler
Which font is the one used in the first few editor screenshots on the Goa
site?

~~~
libria
Pretty sure it's PragmataPro. Dotted zero's, very thin 'm', looptail 'g'.

