I am seeing a lot of new startups trying to solve existing problems surrounding Open API Spec. Speakeasy, Fern, and Liblab are all trying to generate state-of-the-art client SDK using Open API Spec.
I want to take a different approach. I believe the reason why the experience surrounding the Open API toolchain is subpar is because Open API Spec is designed to be an API Documentation format, not for code generations.
I build Json APIs mostly. I need a quick and easy way to write a spec for my APIs, and generate server request/response models and http clients to get end-to-end type safety across my services. If I can get API documentation out of this process, even better.
Instead, doing what is supposed to be simple proves to be nearly impossible with Open API Spec.
First, I have to struggle my way through writing the spec in YAML with no code completion help, and let’s face it, there are way too many fields in Open API Spec supporting all kinds of weird API use cases. Writing it by hand is a tedious and error-prone process. You either are doing a lot of copy pasting or you have to constantly refer to the documentation.
Once I finally come up with a well-crafted Open API spec, I then have to wrestle my way through tons of “official” and “unofficial” code generators out there with varying degrees of Open API Spec support.
I finally find a good generator only to realize the generator outputs different code depending on how you write your spec. Now I am tweaking the spec to get the generator to produce the output that I want. Oops, now my changes in the spec break the output of another generator. At this point, I might as well just develop the whole stack in a dynamically typed language and call it a day.
Enough is enough. I am going to build my own tooling for Open API. Let me try parsing the spec first.
I gave up within 5 minutes. Open API Spec is so open-ended it’s impossible for me to work with it.
It's time to design a new API spec from scratch. Something that is not only lightweight, but also tailored for code generation and schema first design. Maybe it’s even time to ditch ‘restful’ practices altogether and do everything with POST requests. I find restful practices a lot less ‘restful’ than the name suggests. What do you think?
I built a survey to collect pain points surrounding Open API Spec. Please fill it out if you are interested in replacing Open API Spec with something better!
I also put a quick poc demo site together if you want to get a sneak peek of what I am planning to do!
Link to survey: https://tally.so/r/wkWG0d Link to demo site: https://yizy.rootxsnowstudio.com/
You're right that the libraries and code generators for it are a mixed bag, and really can make a difference between it being easy to work with or difficult, but I'm not convinced that's a good reason to start from scratch. Don't let that stop you trying though, if you come up with something good then I'll be there in 10 years to start using it when it's proven itself :D.
The best bits of advice for those looking to use OpenAPI specs with their API are:
1. Make the OpenAPI spec the source of truth - view it as the contract you have with people using your API.
2. If you've got multiple services working with the same data structures then host your JSON Schema separately and reference them in your different OpenAPI specs.
3. Use the versioning in a sensible way, on both your OpenAPI specs and your JSON schema - Semantic versioning works well for me.
4. Make sure your integration tests go through the full routing logic and test your API options (i.e. don't trust the code generators and frameworks).
5. Build your documentation from it - which in turn means that you need to make sure you use the description fields.