
OpenAPI 3.0.3 Specification Released - izbob
https://github.com/OAI/OpenAPI-Specification/releases/tag/3.0.3
======
hardwaresofton
For those who don't know already -- one of the best parts about the OpenAPI
spec is that it allows generation of the clients and servers and the
OpenAPITools/openapi-generator[0] is the tool that does that effortlessly.

If you want to take your CI pipeline to the next level you can run it
(dockerized, if you want) from a CI step to generate and commit + tag a
completely separate repo to have your API SDK generation completely automated.
I've written a little about the dumbest possible way you could do it (i.e.
manually writing YAML)[1] for when you don't have proper framework support.

openapi-generator also has some really awesome new features and support for
different languages, most recent big release was 4.0 (and most recent as of
this post is 4.2.3)[2], been meaning to write a bit about that as well since
their haskell support gets better and better every time. Super awesome &
convenient project, the value being delivered for free is unreal.

[0]: [https://github.com/OpenAPITools/openapi-
generator](https://github.com/OpenAPITools/openapi-generator)

[1]: [https://vadosware.io/post/quick-intro-to-manual-
openapi-v3/](https://vadosware.io/post/quick-intro-to-manual-openapi-v3/)

[2]: [https://github.com/OpenAPITools/openapi-
generator/releases](https://github.com/OpenAPITools/openapi-
generator/releases)

~~~
smt88
I'm a very heavy OAS user across languages (C#, Java, TypeScript, Python).

I've tried both the client and server generators for many languages, and the
output was always unusable garbage.

It's bettee to just write your own server and use OAS for validation and type
defs.

~~~
hardwaresofton
Yeah I disagree -- I personally found the TypeScript client to be quite
usable, but maybe you've hit more edge cases than I have!

Are there any issues for these corner cases you've filed that could use more
attention? I don't maintain openapi-generator but I can definitely forward
them to the maintainers

~~~
fyp
I am currently evaluating whether I want to use the generators for a
typescript node.js/react project.

Which typescript generator are you using? Do you use typescript on the backend
too and if so is it easy to keep the generated type definitions in sync? Also
for backend what do you use for json schema validation?

~~~
wing328hk
I would recommend the `typescript-angular` generator as a starting point for
evaluation as it's pretty active and we just added Angular 9 support.

~~~
hardwaresofton
I used and like typescript-axios

------
theptip
I've found the openapi-generator client in Python to be pretty horrific to
use; very un-idiomatic, hard to follow, and poorly documented.

Any other projects that are better? Or just projects that can do the "POPO <>
JSON" mapping, ideally with type hints so that I can get code completion in my
IDE? I'd be fine to manually wire up the HTTP parts for the SDKs that I write
if I had a good schema mapper.

~~~
wing328hk
Do you mind opening an issue via [http://github.com/OpenAPITools/openapi-
generator/issues/new](http://github.com/OpenAPITools/openapi-
generator/issues/new) with the details? (I assumed you've checked out the
auto-generated documentation and that doesn't look good to you.)

There were discussions on type hints but unfortunately no one has found the
time to make the contribution yet.

We also have a new `python-experimental` client generator that has better
support for new features in OAS v3. Please check it out to see if it works
better for you.

~~~
theptip
Thanks! I'll give the new generator a spin and see what it looks like.

IIRC the problems I faced were around things like bearer token auth with JWT
being confusing to configure, the general structure of the client being
unintuitive for me, and a general lack of examples on how the client was
supposed to be used. No problems that I couldn't resolve each in an afternoon,
but way harder to work with than a hand-rolled SDK (even considering complex
and arguably a bit confusing ones like
[https://developer.paypal.com/docs/api/quickstart/](https://developer.paypal.com/docs/api/quickstart/)).

------
rubyn00bie
I don't really care for Open API's literal spec, but I FUCKING LOVE not
painting bike sheds anymore, and so I fucking love OpenAPI.

So many things have built-in support that _not using_ it is really costing
you. Yeah, sure, the auto-generated clients can suck but mangling that boiler
plate into something acceptable probably saved you days of time, if for
nothing else but being consistent with its shitty quirks. If it wasn't for
OpenAPI I probably would have given up on web-frontends, because it's awful to
give a shit about the shape of your data... but you pair it with Ember, which
is already aware of it OOB, and _kisses the air_ "it's fucking brilliant."

It works. It's easy enough... and to be honest, absolutely none of us, save
for some very real-time, low-latency, applications, have a good reason to not
use it... unless you like painting bike sheds ;)

Oh, and since it's REST, you even get nice things like logs that are useful...
_cough_ GraphQL _cough_

~~~
mister_hn
Yeah but I've found out that the boilerplates don't have OpenID/OAuth code at
all as well, so you have to do it yourself anyways

~~~
chrismmay
Just add this section to "components" at the bottom for OAuth JWT support? Or
are you saying this won't result in code in the client? (sorry the interface
here is mangling yaml).

components: securitySchemes: bearerAuth: type: http scheme: bearer
bearerFormat: JWT

security: \- bearerAuth: []

~~~
mister_hn
The generated boilerplate misses completely on security, which is IMHO a
priority in this kind of things

------
manigandham
OAS is incredibly verbose and the quality varies greatly between languages,
runtimes and the generators being used. It doesn't help that the swagger team
is split from the openapi team with competing codegen products.

I find GRPC to be much better on server-side and grpc-web + webassembly is
starting to be a serious competitor on the frontend as well.

~~~
chrismmay
Fine if you control the clients and the servers, but if you're writing your
API for public consumption, API customers want REST not gRPC.

~~~
DrScientist
Yes REST has a lower bar to entry. However, if you need to you can provide
REST end points from a gRPC definition.

eg [https://levelup.gitconnected.com/grpc-basics-part-2-rest-
and...](https://levelup.gitconnected.com/grpc-basics-part-2-rest-and-
swagger-53ec2417b3c4)

We had the pleasure of working with some legacy SOAP recently - the other end
had changed the WSDL such that our client no longer compiled from the WSDL -
they couldn't work out what was wrong and where fearful of changing it again
so we had to had to hand roll the client. Fun times....

I hope neither get as complex as SOAP - one of potential pitfalls of tooling
is it becomes 'free' to add complexity.

~~~
chrismmay
Our product literally exists to present a single simple interface to
consolidate and orchestrate across dozens of SOAP interfaces. We handle the
complexity so customers don't have to. So I'm glad SOAP exists and is much
more complex than REST.

------
pbreit
Why does every API need its own set of client libraries? Wasn't the promise of
RESTful APIs to obviate the need for such?

Is it perhaps because basic JSON handling and POST/GET processing is still so
miserable in most environments?

~~~
riquito
You have a RESTful API. Good. You now want to communicate with it. You need to
write some code (an SDK) to do the requests, or you can generate it
automatically. If you write it yourself, you have to do it for every language
you use, since you can't reuse SDK between different languages. Even worse, if
you can't generate an SDK every person who access your service will end up
writing different code to talk to your RESTful API.

There are other advantages, like automatic documentation, easier management of
versioning, schema/type verification, ...

~~~
dariusj18
I think their point is, after the API is restful, all SDKs are replaceable
with an Http client.

------
xbhdhdhd
Im using this and couldnt imagine doing API work any other way.

Generators are still in need of work for the languages I use, but this is the
future.

DRY in action

~~~
wing328hk
> Generators are still in need of work for the languages I use, but this is
> the future.

Please share your feedback by opening an issue via
[https://github.com/OpenAPITools/openapi-
generator/issues/new...](https://github.com/OpenAPITools/openapi-
generator/issues/new/). Thanks.

------
chrismmay
Funny, just yesterday I wrote the yaml to describe our API according to this
spec. The lure of writing the spec once and getting 18 different auto-
generated client SDKs is too great to pass up, although I haven't tried any of
them out yet. This course on Linkedin Learning was pretty good. I watch them
at 2x speed... you get used to it, and it saves time. I go back and re-watch
the sections I really care about as needed.

[https://www.linkedin.com/learning/building-apis-with-
swagger...](https://www.linkedin.com/learning/building-apis-with-swagger-and-
the-openapi-specification/achieving-reusability-with-components)

You can run Swagger UI and Swagger editor locally via docker like this:

docker pull swaggerapi/swagger-editor && docker run -d -p 80:8080
swaggerapi/swagger-editor

docker pull swaggerapi/swagger-ui && docker run -d -p 81:8080
swaggerapi/swagger-ui

------
chronomex
Isn't this what SOAP promised? What's different this time?

~~~
jayd16
No one is pretending services will discover and configure themselves. This is
just nice documentation.

You could also do some really horrific things with XML. YAML isn't amazing but
its its a lot more plain. Parsers seems a lot more stable these days because
of that.

------
wenbin
I love OpenAPI!

Listen Notes API is using OpenAPI:
[https://www.listennotes.com/api/docs/#openapi](https://www.listennotes.com/api/docs/#openapi)

------
hbcondo714
How does this compare to the JSON:API spec?

[https://jsonapi.org/](https://jsonapi.org/)

~~~
strzibny
Correct me if I am wrong, but OpenAPI is not telling you how to design your
API. OpenAPI is a way to describe/document your API similarly to API
Blueprint. JSON:API prescribes how your JSON responses should look like.

~~~
yxhuvud
Except OpenAPI is quite opinionated - no union types, no nested query
parameters. There are things in JSON:API that OpenAPI can't document.

------
dariusj18
I tried documenting the Facebook Graph API with OpenAPI. That didn't work
well.

