
AutoRest: OpenAPI Specification code generator - guifortaine
https://github.com/Azure/autorest
======
elcapitan
So that's basically a code-generator for OpenAPI/Swagger specs? How is it
different from swagger-codegen?

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

------
weitzj
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
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
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. :)

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

~~~
vesinisa
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)

------
michaelsbradley
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)

------
tuyguntn
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
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/m...](https://github.com/swagger-api/swagger-
codegen/tree/master/modules/swagger-codegen/src/main/resources/go) You can
create a copy of that template directory, adjust them and pass it as a
parameter to swagger-codegen.

------
whoisthemachine
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
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
[https://github.com/metosin/compojure-
api](https://github.com/metosin/compojure-api) this library uses clojure.spec
with Swagger APIs to check data validity.

