4 ms·

AutoRest: OpenAPI Specification code generator

57 points by guifortaine 9y ago

weitzj 9y ago
We are doing it another way: Start with a gRPC spec -> protoc-gen-swagger (https://github.com/grpc-ecosystem/grpc-gateway https://github.com/grpc-ecosystem/grpc-gateway) I think there is a New York Times Github repo, which does: Swagger -> gRPC
- WhitneyLand 9y ago
  but what’s the point of starting with grpc? I’m sure you have some reasons that is working better for you. would be cool to here any benefits of not just using swagger alone.
  - weitzj 9y ago
    The api is consumed by mobile apps and a website. Therefore, for the apps we actually just need gRPC and its generators for each platform. This way we get protobuf serialization (for free with gRPC). So only the website needs another iteration. And since grpc-web is not finished yet (gRPC in the Browser), we rely on Swagger, following the idea as described here: https://coreos.com/blog/grpc-protobufs-swagger.html https://coreos.com/blog/grpc-protobufs-swagger.html Possible alternatives in the future I can think of, might be: use grpc-web (no more grpc-proxy) use Istio's grpc-bridge https://istio.io/ (https://envoyproxy.github.io/envoy/configuration/http_filters/grpc_json_transcoder_filter.html) Regarding Istio/Envoy grpc-bridge: I don't know if it makes sense to make Istio "too smart", i.e. you suddenly have to install a Go(lang)-generated file (from your proto-definition) on Istio. Therefore I think we stick with the gRPC-proxy solution from CoreOS for now, so that the website developer has the chance to use the api directly without going through Istio. Istio makes sense for tracing and all the other fancy features. :)
elcapitan 9y ago
So that's basically a code-generator for OpenAPI/Swagger specs? How is it different from swagger-codegen?
- AaronKJohnson 9y ago
  I asked the HN community for feedback on using Swagger Codegen, AutoRest last year: https://news.ycombinator.com/item?id=12485310 https://news.ycombinator.com/item?id=12485310 They're essentially the same but written in different languages (Java vs C#/TypeScript). Eventually we picked Swagger Codegen due to its active community and wide-range of supported languages/frameworks.
hugecannon 9y ago
Slightly off-topic: Are there any tools which can validate an OpenAPI Specification against a running instance of the API it describes? I've played around with apiaryio/dredd, but was hoping to find something more targeted towards OpenAPI/Swagger.
- bpicolo 9y ago
  What's the goal? Fwiw, an interesting inverse approach is to define routes/apis/validation directly with swagger specs, which there are a few libraries in various languages for.
- vesinisa 9y ago
  If I undetstood correctly, this might do what you want: https://github.com/cbkelley/swaggerValidator https://github.com/cbkelley/swaggerValidator I have own experience only with "server-side" of Swagger validation. Some time ago, I had to build a simple stateless "gateway" style Node.js backend for a customer webapp. It took API requests, checked authorization and then fetched data from a couple of non-public services, and combined them to a reply JSON for consumption by the frontend webapp. I wanted to keep the backend really simple and have guarantees it was always returning good data, so I could focus on the more complex frontend code. I thought a "specification-driven" approach would be suitable, where I first described my intended backend REST API with Swagger, and then wrote the Node.js code that implemented that REST API specification. Usually, things are done exactly vice-versa: you write the backend code, and then generate the spec that describes your implementation. I think I ended up using the swagger-express-validator library to a) validate incoming JSON/form POST requests, b) automatically select the correct Node.js controller that should serve the request, and c) validate that the HTTP/JSON replies the controller eventually returned were correct (per the Swagger spec). https://github.com/gargol/swagger-express-validator https://github.com/gargol/swagger-express-validator It worked quite well. The Swagger served as kind of a "index" of the backend, similar to a C header file, and if you did an "oops" and returned bad data you would immediately get a fatal error during development. I caught multiple corner cases where the upstream APIs were returning unexpected data that would have normally been only discovered by monkey testing the UI. This library allows choosing the NodeJS/Express controller by a Swagger spec, but I think I ended-up rolling my own: https://github.com/swagger-api/swagger-node https://github.com/swagger-api/swagger-node
whoisthemachine 9y ago
This reminds of the SOAP/WSDL days. The lesson learned from those days is that if your API is complicated enough that you are needing to use such tools, then you should really do some analysis into how you can simplify your API.
- chrismorgan 9y ago
  It’s all about having a machine-readable definition of the API. When you have that, you can support strictly-, strongly-typed languages much better. In a language like C, Java or Rust, which would you rather: a JSON data type that is essentially Map<String, Object>, or a struct (or class, or whatever) that actually represents the fields and types that exist? It’s useful to be able to quickly generate a client library with fair ergonomics for such languages, rather than having to use a weakly-typed, string-heavy general-purpose HTTP library. Languages like JavaScript, Ruby and Python don’t benefit so much from things like this, but even so there are definite advantages to it.
  - vesak 9y ago
    https://github.com/metosin/compojure-api https://github.com/metosin/compojure-api this library uses clojure.spec with Swagger APIs to check data validity.
- organsnyder 9y ago
  Your API is a contract you're extending to your customers. You need to be able to specify the behavior of a given operation with enough precision that you and your customer have a good understanding of how it will work. The problem with SOAP/WSDLs is that you break the contract every time you sneeze at the damn thing (adding a field, etc.). Swagger/OpenAPI is generally more permissive, as long as you know what you're doing. API versioning is hard, regardless of the tool you use. Contract-first API design prioritizes predictability over fluidity. The decision on which trade-offs are correct will depend on the context.
- niftich 9y ago
  On the contrary; the lesson learned from those days is that codegens and declarative inputs to codegens (i.e. API specs) have their place, despite the particular stack falling out of fashion. APIs that were put out when the "RESTful" movement was at its peak were documented solely in prose, a big regression from the WSDL days. OpenAPI (or a few years ago, Swagger and its contemporaries RAML and API Blueprint) attempt to retrofit what we've lost. Spec-driven codegens allow shops that put out APIs to quickly bootstrap first-party clients, gaining an instant competitive advantage over similarly-positioned competitors who don't publish a first-party client.
tuyguntn 9y ago
swagger-codegen does this fairly good, how about server side code generation? swagger-codegen also does this, but not so good if you are targeting golang for example
- elcapitan 9y ago
  It's fairly easy to modify for your needs though, have a look at the templates: https://github.com/swagger-api/swagger-codegen/tree/master/modules/swagger-codegen/src/main/resources/go https://github.com/swagger-api/swagger-codegen/tree/master/m... You can create a copy of that template directory, adjust them and pass it as a parameter to swagger-codegen.
- wing328hk 9y ago
  Hi, for any feedback on the Go server stub generator, please let us know via https://github.com/swagger-api/swagger-codegen/issues/new https://github.com/swagger-api/swagger-codegen/issues/new. Also worth sharing with you that the Go client generator in the latest master (2.3.0) has been refactored. Please give it a try and let us know if you've any feedback. Disclosure: I'm a top contributor Swagger Codegen
michaelsbradley 9y ago
Developers working with Django might look at pairing use of this with DRF OpenAPI: https://github.com/limdauto/drf_openapi https://github.com/limdauto/drf_openapi

57 points by guifortaine 9y ago

We are doing it another way: Start with a gRPC spec -> protoc-gen-swagger (https://github.com/grpc-ecosystem/grpc-gateway https://github.com/grpc-ecosystem/grpc-gateway) I think there is a New York Times Github repo, which does: Swagger -> gRPC

WhitneyLand 9y ago
but what’s the point of starting with grpc? I’m sure you have some reasons that is working better for you. would be cool to here any benefits of not just using swagger alone.
- weitzj 9y ago
  The api is consumed by mobile apps and a website. Therefore, for the apps we actually just need gRPC and its generators for each platform. This way we get protobuf serialization (for free with gRPC). So only the website needs another iteration. And since grpc-web is not finished yet (gRPC in the Browser), we rely on Swagger, following the idea as described here: https://coreos.com/blog/grpc-protobufs-swagger.html https://coreos.com/blog/grpc-protobufs-swagger.html Possible alternatives in the future I can think of, might be: use grpc-web (no more grpc-proxy) use Istio's grpc-bridge https://istio.io/ (https://envoyproxy.github.io/envoy/configuration/http_filters/grpc_json_transcoder_filter.html) Regarding Istio/Envoy grpc-bridge: I don't know if it makes sense to make Istio "too smart", i.e. you suddenly have to install a Go(lang)-generated file (from your proto-definition) on Istio. Therefore I think we stick with the gRPC-proxy solution from CoreOS for now, so that the website developer has the chance to use the api directly without going through Istio. Istio makes sense for tracing and all the other fancy features. :)

elcapitan 9y ago

So that's basically a code-generator for OpenAPI/Swagger specs? How is it different from swagger-codegen?

AaronKJohnson 9y ago
I asked the HN community for feedback on using Swagger Codegen, AutoRest last year: https://news.ycombinator.com/item?id=12485310 https://news.ycombinator.com/item?id=12485310 They're essentially the same but written in different languages (Java vs C#/TypeScript). Eventually we picked Swagger Codegen due to its active community and wide-range of supported languages/frameworks.

hugecannon 9y ago

Slightly off-topic: Are there any tools which can validate an OpenAPI Specification against a running instance of the API it describes? I've played around with apiaryio/dredd, but was hoping to find something more targeted towards OpenAPI/Swagger.

bpicolo 9y ago
What's the goal? Fwiw, an interesting inverse approach is to define routes/apis/validation directly with swagger specs, which there are a few libraries in various languages for.
vesinisa 9y ago
If I undetstood correctly, this might do what you want: https://github.com/cbkelley/swaggerValidator https://github.com/cbkelley/swaggerValidator I have own experience only with "server-side" of Swagger validation. Some time ago, I had to build a simple stateless "gateway" style Node.js backend for a customer webapp. It took API requests, checked authorization and then fetched data from a couple of non-public services, and combined them to a reply JSON for consumption by the frontend webapp. I wanted to keep the backend really simple and have guarantees it was always returning good data, so I could focus on the more complex frontend code. I thought a "specification-driven" approach would be suitable, where I first described my intended backend REST API with Swagger, and then wrote the Node.js code that implemented that REST API specification. Usually, things are done exactly vice-versa: you write the backend code, and then generate the spec that describes your implementation. I think I ended up using the swagger-express-validator library to a) validate incoming JSON/form POST requests, b) automatically select the correct Node.js controller that should serve the request, and c) validate that the HTTP/JSON replies the controller eventually returned were correct (per the Swagger spec). https://github.com/gargol/swagger-express-validator https://github.com/gargol/swagger-express-validator It worked quite well. The Swagger served as kind of a "index" of the backend, similar to a C header file, and if you did an "oops" and returned bad data you would immediately get a fatal error during development. I caught multiple corner cases where the upstream APIs were returning unexpected data that would have normally been only discovered by monkey testing the UI. This library allows choosing the NodeJS/Express controller by a Swagger spec, but I think I ended-up rolling my own: https://github.com/swagger-api/swagger-node https://github.com/swagger-api/swagger-node

whoisthemachine 9y ago

This reminds of the SOAP/WSDL days. The lesson learned from those days is that if your API is complicated enough that you are needing to use such tools, then you should really do some analysis into how you can simplify your API.

chrismorgan 9y ago
It’s all about having a machine-readable definition of the API. When you have that, you can support strictly-, strongly-typed languages much better. In a language like C, Java or Rust, which would you rather: a JSON data type that is essentially Map<String, Object>, or a struct (or class, or whatever) that actually represents the fields and types that exist? It’s useful to be able to quickly generate a client library with fair ergonomics for such languages, rather than having to use a weakly-typed, string-heavy general-purpose HTTP library. Languages like JavaScript, Ruby and Python don’t benefit so much from things like this, but even so there are definite advantages to it.
- vesak 9y ago
  https://github.com/metosin/compojure-api https://github.com/metosin/compojure-api this library uses clojure.spec with Swagger APIs to check data validity.
organsnyder 9y ago
Your API is a contract you're extending to your customers. You need to be able to specify the behavior of a given operation with enough precision that you and your customer have a good understanding of how it will work. The problem with SOAP/WSDLs is that you break the contract every time you sneeze at the damn thing (adding a field, etc.). Swagger/OpenAPI is generally more permissive, as long as you know what you're doing. API versioning is hard, regardless of the tool you use. Contract-first API design prioritizes predictability over fluidity. The decision on which trade-offs are correct will depend on the context.
niftich 9y ago
On the contrary; the lesson learned from those days is that codegens and declarative inputs to codegens (i.e. API specs) have their place, despite the particular stack falling out of fashion. APIs that were put out when the "RESTful" movement was at its peak were documented solely in prose, a big regression from the WSDL days. OpenAPI (or a few years ago, Swagger and its contemporaries RAML and API Blueprint) attempt to retrofit what we've lost. Spec-driven codegens allow shops that put out APIs to quickly bootstrap first-party clients, gaining an instant competitive advantage over similarly-positioned competitors who don't publish a first-party client.

tuyguntn 9y ago

swagger-codegen does this fairly good, how about server side code generation? swagger-codegen also does this, but not so good if you are targeting golang for example

elcapitan 9y ago
It's fairly easy to modify for your needs though, have a look at the templates: https://github.com/swagger-api/swagger-codegen/tree/master/modules/swagger-codegen/src/main/resources/go https://github.com/swagger-api/swagger-codegen/tree/master/m... You can create a copy of that template directory, adjust them and pass it as a parameter to swagger-codegen.
wing328hk 9y ago
Hi, for any feedback on the Go server stub generator, please let us know via https://github.com/swagger-api/swagger-codegen/issues/new https://github.com/swagger-api/swagger-codegen/issues/new. Also worth sharing with you that the Go client generator in the latest master (2.3.0) has been refactored. Please give it a try and let us know if you've any feedback. Disclosure: I'm a top contributor Swagger Codegen

michaelsbradley 9y ago

Developers working with Django might look at pairing use of this with DRF OpenAPI: https://github.com/limdauto/drf_openapi https://github.com/limdauto/drf_openapi