About
@nahkies/openapi-code-generator is a CLI tool that aims to generate high quality typescript client SDK's,
and API server scaffolding (routing, validation, serialization) from OpenAPI 3 specifications.
Currently, OpenAPI 3.0 (opens in a new tab), OpenAPI 3.1 (opens in a new tab), and TypeSpec (opens in a new tab) are supported an input specifications.
The following templates are supported.
Server Scaffolding Templates
Client SDK Templates
Project Goal / Principals
To make it fun, easy and productive to generate both client and server "glue" code from openapi 3 definitions. This is code that is tedious and error-prone to maintain by hand, by automating it we can reduce toil and frustration.
The generated code output should be "stable" in the sense that it will not arbitrarily change between generation without need (for a given version). For example outputting entities in alphabetic order where possible.
It should also be generated in a way that human would reasonably write it, the intent is that the generated code can and should be committed to the consuming project repositories, allowing it to be reviewed, and audited overtime.
This is particularly useful in the case of mistakes in the generation or schemas, and also serves to reduce risk of adoption. There should be no lock-in - if you wish to stop using the code generation, you can simply start maintaining the previously generated code by hand.
The initial focus on typescript, with an intention to later support other languages. kotlin
is the most likely candidate for a second language.
Why schema first
Broadly speaking there are two approaches people take to maintaining API specifications:
- Schema first, where you write the schema by hand
- Code first, where you generate the schema from your code
This project being a code generator from API specification files is on the schema first side of the debate, but why?
Ultimately this is fairly subjective, but there are four primary motivators that lead us to believe schema first is the better approach.
Longevity
APIs are forever (opens in a new tab), changing them in backwards incompatible ways is hard/expensive, or sometimes not possible.
With that in mind, we believe it's important to be thoughtful about your API design, and that writing an explicit specification/contract is a great forcing function to accomplish this.
Additionally, programming languages / frameworks come and go - they are an implementation detail, and subject to change as business requirements evolve. OpenAPI (originally Swagger) has been around for over a decade now, and we're confident it'll be around for a long time.
Common Language
Many large projects / systems will involve multiple programming languages. For example, you might have a Java backend, Kotlin Android app, Swift iOS app, and Typescript web frontend.
For writing your API contracts using OpenAPI up front, you create a common ground for developers of all languages to discuss and hash out the details.
Constraints
Turing complete programming languages are very flexible. If you try hard enough, you can probably implement it. Specifications like OpenAPI on the other hand are more rigid and constraining.
We believe it's better to lean into this and design your systems in ways that can be represented fully by a specification, rather than attempt to generate a specification from the implementation and potentially lose information/nuance in the process.
Separation
A good specification not only defines the API contract, but also includes a lot of supplementary information such as examples, and documentation.
Generating a good specification from your code, therefore requires including all this extra metadata in the code, which can make the code more difficult to work with.
We prefer to separate these concerns out into the specification, and keep the implementation code leaner and simpler.
Compatibility / Completeness
This project should be considered beta quality, and is still pre-v1.
It does not yet handle all aspects of the OpenAPI / JSON schema specification, but most common features are implemented.
In particular at the moment only JSON content types are supported properly.
You can get a sense of what works by looking at the compatibility tables, or the Github issues (opens in a new tab) (non-exhaustive). However often the best way is to just try it out with your API specification and see what happens!
The integration tests (opens in a new tab) also act as a good showcase of the sort of output you can expect.
Compared to other projects
There are many similar projects out there, so why should you use this one?
- Strong emphasis on "human like" code output
- Tackles the program space from both ends - client and server
- Comprehensive runtime parsing/validation in addition to static compile time safety
So if you want a low risk, write-once, get strong build & runtime guarantees experience then we're worth giving a try.
If you're looking to achieve the minimal runtime bundle size in your web frontends, then this project probably isn't for you (try OpenAPI TypeScript (opens in a new tab) instead).