[kentonv]

I admit I haven't written an OpenAPI schema myself. But, looking at the docs, I have a hard time imagining that I'd want to do API-driven development with it. Let me explain what I mean by that...

When I start a new project, or a major new feature in an existing project, usually the first thing I do is write out the Protobuf or Cap'n Proto schemas describing the APIs and data structures. Even for internal-facing APIs. APIs are how components talk to each other, and defining the APIs defines which components are responsible for what in a very clear way. Often I find writing out the APIs is actually the easiest, most precise way to communicate a design with my teammates; much better than prose in a design doc.

For this purpose, it's actually pretty important that the schema language be something that's not cumbersome to write. Protobuf and Cap'n Proto feature dedicated schema languages that feel like a programming language. It looks like OpenAPI has you writing schemas themselves in JSON or YAML. Ick.

And once I've written those schemas, I run the code generator and poof, I now have nice, type-safe classes in my programming language of choice implementing my schema. This lets me move a lot faster implementing, being able to use my IDE's auto-complete and whatnot. Does OpenAPI generate code for you? I have worked on projects that use it and didn't have any generated code, so I am assuming not...

I think this is what the article is trying to get at.

(Disclosure: I'm the author of Cap'n Proto; long ago I was the author of Protobuf v2; and I am a (small) investor in Buf because I like what they're doing, but I don't work with them.)

[hashamali]

OpenAPI is just the format for describing APIs for various use cases such as documentation, runtime validation, and yes, even code generation. Depending in the language you use, the support for code generation may vary though.

I’m certainly not against the flow you’re describing. Aside from having to wrangle JSON/YAML instead of a more concise DSL, it’s not too different from what you’d do with OpenAPI.

[ccleve]

Nobody writes OpenAPI directly. You use an API design tool for that.

There are two ways to design APIs: code-first and design-first.

With code-first you write your code and then automatically generate the OpenAPI spec from that. I do it in Java using JAX RS and it works fine. It is strongly-typed and has all of the same advantages you get by designing your protobuffers first.

The world is moving toward design-first, though. You use a tool to write your API and then generate code from that. It's a nice idea, but I'm not there yet because I don't like the tooling.

I expect that in a few years the tooling will be good and we'll be able to generate both APIs and database schemas in one place. Looking forward to it.

[wing328hk]

> Does OpenAPI generate code for you? I have worked on projects that use it and didn't have any generated code, so I am assuming not...

Please give OpenAPI Generator [1] a try to generate clients, servers stubs, documentation, schemas (graphql, protobuf, etc) and more. It supports many programming languages and many companies are already using it [2]:

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

[2] https://openapi-generator.tech/users

(Disclosure: I'm the top contributor to OpenAPI Generator)

[mayank]

> Does OpenAPI generate code for you?

An OpenAPI spec is the equivalent of your .proto files. You need codegen to go from your .proto files to native classes, and you need codegen to go from your OpenAPI spec to native.

> Protobuf and Cap'n Proto feature dedicated schema languages that feel like a programming language. It looks like OpenAPI has you writing schemas themselves in JSON or YAML. Ick.

Counterpoint: I can take an OpenAPI spec and parse/process/render/codegen it in every single language without a custom parser library.

[Shorel]

Your counterpoint makes no sense...

And Protobuf has generators for more languages than OpenAPI/Swagger.

[wing328hk]

FYI. OpenAPI Generator supports many programming languages and server-side frameworks: https://github.com/OpenAPITools/openapi-generator#overview

This is not to say it has more languages supported than Protobuf as I do not know exactly how many generators out there supporting Protobuf.

(OpenAPI Generator also comes with the generator/converter that converts OpenAPI spec documents into gRPC and protocol buffer schema files. Not sure if OpenAPI Generator is also counted as a generator for Protobuf)

[erpellan]

One of my issues with schema languages is that they're not actually languages. Having used kotlin's typesafe builders a few times, other mechanisms feel hamstrung by comparison.

[mtoddsmith]

With OpenAPI you can use an API editor

https://swagger.io/tools/swagger-editor/

Sure you're writing YAML/JSON but the editor is type checking in real-time and enforcing the schema.