What is the point of using OpenAPI at all? [closed]

Question

I didn't come from a background using OpenAPI or anything like it, even though I built and used REST APIs in my day job over and over again. In my current role, we always have OpenAPI specs defined, and it seems to be an assumed part of the process. The team treats it as very important.

However, I cannot for the life of me recognize a single benefit to it. I'm trying to understand better.

Of the things I know it can do, none of them appear to be beneficial, imho, but I have to be missing something.

• OpenAPI specs can generate documentation, but documentation is for humans to read and should be written by human, in my opinion. Generated docs might include all the bits, but none of the context and nuance of using the API as a whole.
• OpenAPI specs can generate client code in many languages for a single API. These are just going to map the REST URL structure to method names, usually. Is that really helpful? It means I might do client.books.get(title="Moby Dick") instead of client.get("/books", {'title': 'Moby Dick'}). All its doing is shifting around the same names, not making anything necessarily easier or more concise. So, again, what's the point? A generated client doesn't seem to actually add anything at all.

Can anyone enlighten me?

Answer 1

OpenAPI specs are not a beneficial thing by themselves. In my experience they are a huge benefit in micro service environments where a lot of services interact with each other.

Like all interfaces, RESTful interfaces can be considered as contracts between service providers and service consumers.

The provider promises to offer a certain set of operations and the consumer can subscribe to these operations and their respective endpoints.

The OpenAPI spec in this case is the contract bill on which the participants can agree on. If they don't agree in the first place, they have the api spec to negotiate over.

This is a non technical aspect, of course.

Among the more technical aspects there are three that I find quite useful

1. Generate code and documentation from one single source

There are a couple of ugly truths when it comes to documentation: No one likes to write it, no one likes to read it and most of the time, it is outdated.

With OpenAPI spec and other similar tools, you have the spec that is used to generate the actual code and at the same time the documentation. The chances are a little bit higher that neither of them get out of date. However, the chances still are not 100%.

2. No need to write boilerplate code

With OpenAPI spec, there is no longer the need to manually implement data classes, and simple client- and server code. For a lot of use cases, you can omit setting up your project -- you don't need to write a spring-boot-server or the java data transfer objects. If you have the api spec, the generator will do that for you.

This is not a big thing when you are dealing with a simple api that only offers a handful of endpoints and data objects. But as soon as you are facing several hundreds of endpoints and data classes (as I have), things get a lot easier with a good written api spec at hand.

3. Tooling

A lot of tools exist in the open api ecosystem (see this list). It is not just the code generator.

There is an awesome in-browser editor for spec files, there are data validators, test data generators etc.

TL;DR

You are right of course. Basically OpenAPI and the whole tool suite behind it will generate client- and server- code and act as a mapper between the rest endpoints and that generated code.

But writing mapping code can be tedious and error prone. Better let some tool do it for you.

Additionally, a machine readable api spec can serve as an api contract bill. It can be versioned on a git repository and distributed over a nexus repo.

If used right, it can make your life a lot easier.