Welcome
@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, OpenAPI 3.1, and TypeSpec are supported an input specifications.
This gives you amazing auto-complete, and compile-time safety. Typescript’s expressive type system is used to make the generated clients feel idiomatic, and as close to handwritten as possible.
Already know that code generation will save you time? Jump straight in with the quick start guide
Server Scaffolding Templates
Server templates handle the routing setup, request and response validation/serialization so that you can focus on the business logic.
Client SDK Templates
Client templates give you a strongly typed interface to your remote server calls, ensuring that you never misspell a field name or route again.
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.
Compatibility / Completeness
This project should be considered beta quality, though it’s getting close to a v1 release.
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 roadmap. However often the best way is to just try it out with your API specification and see what happens!
The integration tests 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, for a single source of truth
- 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.