There is a small video demo if you don’t quite understand what I wanted to describe below.
OpenApi4s Demo
I’ve wanted to implement something like this for a really long time.
TLDR: it is an incremental generator, meaning:
- first time (when there are no files generated) it will just write the generated files
- next time it runs, it will not touch the code that you added manually. It only “maintans” the code that it generated (refactors if needed).
- only adds new properties/methods/classes (no deletions, you have to clean up manually if something is removed from the spec)
- if something is not supported it will still (mostly) work, so you can adapt your openapi spec to work gradually
Benefits:
- more stable API, no playing russian roulette with code-first OpenApi generators like with Tapir and Spring annotations
- no messing with Tapir implicits, less code in your final app
- you can see the git diff of both spec you changed + code that implements it, everything is plain obvious
There are some limitations of course:
- JSON only
- only named entities, no anonymous objects
- no comments in source code (scalameta limitation)
- scalafmt is almost mandatory (if you care about nice/minimal git diffs)