OpenAPI 3.0.3 Specification Released

https://github.com/OAI/OpenAPI-Specification/releases/tag/3.0.3

by izbob • 6 years ago

69 59 6 years ago

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

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

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

moltar• 6 years ago

To add to your useful comment I’d like to suggest the Stoplight desktop editor (electron app).

I’ve tried pretty much all GUIs that existed a year ago or so, and started with Apicurio which was good, but was missing support for oneOf, allOf and the like.

Switched to Stoplight and it has been great! Love that you can just manage your spec in a repo along with the project.

smt884• 6 years ago

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.

hardwaresofton5• 6 years ago

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

dnautics2• 6 years ago

This might sound crazy but I wound up writing my own generator and was quite happy with the result (and use it in prod).

hopia2• 6 years ago

With OpenAPI spec < 3 there's no support for sum types. This at least for me lead to semi heavy refactoring of the client lib (for Dart lang).

nmfisher2• 6 years ago

Having used the TypeScript client generator and contributed the F#/Giraffe and F#/Azure Functions server generators, I disagree :)

Do you literally mean unusable, or it just didn't fit your stylistic preference?

kelnos• 6 years ago

We built guardrail[0] because we weren't happy with the output of the reference generators. We only support Java (Dropwizard) and Scala (akka-http, http4s, and endpoints.js) so far, however.

[0] https://github.com/twilio/guardrail

james_s_tayler3• 6 years ago

Agreed. We have opted to write our own clients so we have full control over how the HTTP calls happen, but we use the models generated by OAS tooling as a happy medium.

glun• 6 years ago

I've been investigating their generators for work these last two days, and their java generators produce code that doesn't even compile -- when ran on their own schema examples! Total garbage. OneOf (for the polymorphism aspect of inheritance) is the feature that breaks every single one of them.

Cthulhu_• 6 years ago

I've had multiple experiences with the generators. I've used it purely to generate the models themselves, doing the APIs (which were usually straightforward REST calls anyway) directly.

I've also written customized templates that removed a lot of the cruft (iirc the JS or TS generator decided to output an API client in three different flavors). Of course the problem there was that the particular generator did not have all code generation in (overridable) templates, but also some hardcoded.

yxhuvud2• 6 years ago

The part about generating clients and servers is the part that has always been the least interesting to me, and the part that I wish hadn't been a goal, because it means bending over backwards to not break the generators. This has really hurt the descriptive power of OpenAPI.

If a viable API documentation tool based on raw unmodified jsonschema with some additions to be able to describe the HTTP actions and parameters, and with the ability to visualize it as documentation, came around then I'd switch in a heartbeat.

hardwaresofton5• 6 years ago

Today is your lucky day! Have you heard of jsonschema[0]'s hyperschema[1][2]?

[0] https://json-schema.org

[1] https://datatracker.ietf.org/doc/draft-handrews-json-schema-...

[2] https://json-schema.org/implementations.html#hyper-schema

xbhdhdhd• 6 years ago

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

inetknght• 6 years ago

I would be happier if it supported more than just HTTP-based request/response paradigms. Message queue protocols also stand to benefit from a common specification like this but trying to describe a message queue using OpenAPI is... a lot more difficult.

wing328hk4• 6 years ago

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

pbreit3• 6 years ago

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• 6 years ago

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

dariusj182• 6 years ago

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

pbreit3• 6 years ago

But an SDK is unnecessary for POSTing JSON back and forth.

jayd162• 6 years ago

You could argue that OpenAPI is actually just a make-good on the HATEOS part of REST and not a new addition.

And of course you don't need a custom library. Its just nicer to have one as it facilitates code completion and leverages the compiler you're using instead of some new validation tool.

james_s_tayler3• 6 years ago

Yeah. This is where I find libraries like Retrofit / Refit suit the model will. Very easy to just declare clients. I like using the models generated by OpenAPI tooling in conjunction with those type of libraries to build clients quickly while being able to maintain control over how the HTTP calls are happening.

I'm bearish on 3rd party SDKs for apis these days as most are fairly thin wrappers around apis that don't add much value but give you little to no control over how the actual http calls are being made.

executesorder66• 6 years ago

Tip: the word obviate means to make something unnecessary.

So you don't need to add "the need" after the word obviate.

You can just say "Wasn't the promise of RESTful APIs to obviate this?"

Otherwise what you are really saying is -> "Wasn't the promise of RESTful APIs to remove the need the need for such?"

pbreit3• 6 years ago

I dunno. To make the need unnecessary seems OK.

GonzaloQuero• 6 years ago

You don't need these clients, though, they're just doing HTTP. Isn't this just a quick way of reducing boilerplate?

rubyn00bie• 6 years ago

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_hn2• 6 years ago

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

chrismmay4• 6 years ago

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: []

chronomex• 6 years ago

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

jayd162• 6 years ago

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.

cbornet• 6 years ago

Yes, HTTP+Json API is not very different from SOAP. But it's not the fault of OpenAPI if everybody does them. At least OpenAPI and OpenAPI-generator fill the gaps that were missing (an IDL and contract based code generation)

wenbin• 6 years ago

I love OpenAPI!

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

theptip2• 6 years ago

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.

odiroot• 6 years ago

At my current company, we decided to write our own library to consume Open API Spec (3.0+) and expose all the endpoints as marshmallow-validated functions. No code generation at all. The library just dynamically exposes proper structure depending on the spec.

wing328hk4• 6 years ago

Do you mind opening an issue via 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.

theptip2• 6 years ago

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/).

chrismmay4• 6 years ago

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

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

hbcondo714• 6 years ago

How does this compare to the JSON:API spec?

https://jsonapi.org/

strzibny• 6 years ago

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.

yxhuvud2• 6 years ago

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

manigandham• 6 years ago

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.

chrismmay4• 6 years ago

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• 6 years ago

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

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.

dariusj182• 6 years ago

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

OpenAPI 3.0.3 Specification Released

Related Stories