The benefits of code generation and the problems of the OpenAPI spec
Code generation is an interesting concept, some developers see it as useless and some think that it is the holy grail to productivity. In a previous post I have talked about the code generation problems of JSON Schema (which is used inside OpenAPI) and TypeSchema a new specification which we have developed to solve those problems. With this post I want to take a look at the bigger picture and why it is in the long term inevitable for the OpenAPI spec to solve those problems.
I will start to make a bold claim so please stay calm:
Currently there is no useful working code generator available for OpenAPI
You will probably directly point me to the OpenAPI generator project which is probably the most popular solution to generate code based on an OpenAPI spec. While it is a great project, from our point of view it fails as a code generator since it has to deal with the fundamental design problems of JSON Schema regarding code generation, which can not be solved at the code generator level. Please let me explain and show you those problems.
We will use the a slightly modified version of the petstore example and add some cases which is complete valid JSON schema and which is probably a problem for every available code generator. I have put the complete YAML also on GitHub so that you can reproduce the results.
If we now use the OpenAPI generator to generate a TypeScript client this will result in the following Pet model:
You can see the complete file also on GitHub. You can see that the generated code is really ugly. The “OneOfCategoryTag” and “OneOfobjectobject” model are also not generated so the code is not functional. Despite this we also lost some type information i.e. the “simpleAllof” becomes an any value. You could argue that this specific generator is maybe not the best but I am pretty confident that you will not find a code generator which can produce useful code for this OpenAPI specification. This is simply due to the problems of JSON schema in regards to code generation, please take a look at our last post which describes those problems in detail.
Solution
Ok we have now found out that code generation and OpenAPI is currently not in a great state but I can tell you that we are currently working on a solution to make this much better. Let me introduce you to TypeSchema. TypeSchema is a new specification to describe data models. Lets take the example from the petstore and convert it to a TypeSchema specification:
You can see the complete file also on GitHub. As you can see some things have changed. At TypeSchema we have several rules which makes the generation of code much easier and unambiguously i.e. you are not allowed to have inline objects and you can reference types directly without the use of JsonPointer. If you use our code generator you can transform this specification into the following TypeScript code:
This looks really sexy and can be used at any client or server code. Through TypeSchema we don`t loose any type information and we have a stable model to describe out data.
We have already build up a library of TypeSchema specifications for popular specs i.e. OpenAPI, AsyncAPI, OpenRPC, etc. please take a look at our repository. Currently we use TypeSchema extensively at our main project Fusio which is an open source API management system, there we generate our complete client SDK based on those models.
To rollback to the beginning, we think that code generation is a really powerful tool which can make communication between different services much easier. We envision a future where every developer can easily generate useful client or server code based on a specification. There is currently no clear path for the OpenAPI spec how to solve this problem since they are bound to JSON Schema. So we can currently only see how this evolves but in the end we think that it is a crucial peace for adoption and developer ux.
But at the meantime you can simply switch to TypeSchema and transform your spec easily to JSON Schema so that you can use it inside an OpenAPI spec. This is also how we have done it at Fusio and we can easily change our generators if a new specification appears. So we hope that we could give you an overview about the current state of code generation and please let us know if you have any feedback or questions.
