My Experiences with the OpenAPI Generator

• My Experiences with the OpenAPI Generator
• You are your own support
• Its a hobby project
• BYO Automation
• Summary

Just a quick disclaimer, I am currently employed by Speakeasy, but the opinions expressed in this post are my own.

My Experiences with the OpenAPI Generator

Something I get asked about a lot (like ALOT) is what I think of the open source OpenAPI generator, so I wanted to finally get my thoughts down in writing.

It is amazing in concept, aimed at supporting a breadth of generation targets both client and server side, but in reality it is flat out, a pretty bad experience: the documentation is bad, the generated code is often broken, and its language design choices are questionable.

You are your own support

Now with all open source tooling there is often a trend of maintainers burning out, projects being abandonded, or other shenanigans, thankfully the OpenAPI generator has a fairly active core team. That being said the heavy support burden, the evolving complexity of the OpenAPI landscape, and the small team size mean the project has largely stagnated over the years.

Since individual generator targets are managed independantly, meaning that there can be a SINGLE PERSON maintaining the generation templates and logic for an entire language.

That, combined with some of the stranger design decisions, and limitations in the core Java packages logic, and you will quickly find yourself breaking glass to manually add the features, customization, or even basic functionality you want.

All meaningful package customization with the OpenAPI generator requires you to manually edit the mustache templates for a given language, and editing mustache templates is not a fun experience. You get all of the misery of writing code in powerpoint, with none of the benefits of an IDE, LSP, or even a linter.

Its a hobby project

The OpenAPI generator is made by and for hobbyists. Don’t get me wrong, its a great free option for hobbyists, especially if you wanted to write everything from scratch in the first place. For everyone else, including hobbyists without unlimmited free time, run the other way.

It lacks quality, design standards, and quality user experience. It causes excessive developer friction, for both those using its tooling, and the tools it creates.

Here are some key things to keep in mind:

• A total of 8,291 issues have been opened over the last 7 years, with 4,340 still being open today, and a trend of 10% more issues being created year over year.
• No enterprise support is available, and you are on the hook to fix all issues you find.
• Any business considering using this tool, know it requires a significant resource investment from your team to design, plan, and implement a solution for a single SDK.
• Generation targets are contributed to by the community and have no guarantee of quality or security.
• OpenAPI support varies greatly between the 75 different generation templates, and every language template is developed in a bubble, with different design approaches and philosphy from all other target.

There are huge variations in support from one target to the next, there is no consistency or common design philosophy, that leads to a wildly different developer experience with every language, and every target used.

BYO Automation

All automation is fully self service, expect to be:

• Scaffolding a Java environment in your CI/CD pipeline
• Curling or commit a versioned java binary
• Downloading and commiting static mustache templates
• Executing the java binary with a very specific set of arguments and configuration files
• Manually editing companion files, versioning package files, managing dependencies, and writing tests
• Editing static mustache templates to add any level of customization or custom functionality

And be ready to rebuild every step from scratch when a version change occurs, you want to.

Summary

I think it really comes down to whether you want to build or buy, If you want to build everything yourself, generating code or using the OpenAPI generator templating system can be a good time saver, but if you would rather buy and have a reliable, feature rich, and custom tailored solution, you should look elsewhere.

This post is all about my opinions and experiences, so I won’t shy away from mentioning alternatives.

I have used a number of other tools and platforms, and nothing holds a candle to Speakeasy.

Speakeasy is by far the most advanced, customizable, feature rich, and most reliable generation tool I have used.

I liked it so much I joined the team.

Be good people, and happy coding.