4 ms·

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

by cakoose 10y ago

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 10y ago
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 10y ago
  Swagger can also generate its spec from an already written server, and that's how I'm using it primarily.
  - niftich 10y ago
    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/
    - tokenizerrr 10y ago
      I'm using Java Spring (so JAX-RS) and use https://github.com/swagger-api/swagger-core https://github.com/swagger-api/swagger-core. To further customize it I use the annotations https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X https://github.com/swagger-api/swagger-core/wiki/Annotations...
    - wing328hk 10y ago
      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.
templaedhel 10y ago
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 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 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/examples/todo-list/restapi/configure_todo_list.go#L33-L35 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/generator/templates/schemavalidator.gotmpl 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.
- wing328hk 10y ago
  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 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 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=%E2%9C%93&q=is%3Apr%20is%3Aclosed%20label%3A%22Client%3A%20Go%22%20created%3A%3E%3D2016-01-22%20 https://github.com/swagger-api/swagger-codegen/pulls?utf8=%E...

by cakoose 10y ago

niftich 10y ago

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 10y ago
Swagger can also generate its spec from an already written server, and that's how I'm using it primarily.
- niftich 10y ago
  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/
  - tokenizerrr 10y ago
    I'm using Java Spring (so JAX-RS) and use https://github.com/swagger-api/swagger-core https://github.com/swagger-api/swagger-core. To further customize it I use the annotations https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X https://github.com/swagger-api/swagger-core/wiki/Annotations...
  - wing328hk 10y ago
    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.

templaedhel 10y ago

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 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 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/examples/todo-list/restapi/configure_todo_list.go#L33-L35 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/generator/templates/schemavalidator.gotmpl 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.

wing328hk 10y ago
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 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 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=%E2%9C%93&q=is%3Apr%20is%3Aclosed%20label%3A%22Client%3A%20Go%22%20created%3A%3E%3D2016-01-22%20 https://github.com/swagger-api/swagger-codegen/pulls?utf8=%E...