Hi Dmitri, Thanks a lot for starting this discussion!
There are many ways to verify whether an OpenAPI change breaks backwards compatibility. For Java types (and other things), there is revapi, which is relatively simple to add to the Gradle build. The only downside is that it has to run against a previously released version emitting the same "set of Java types." Technically, revapi can check Java ABI compatibility of the current state against a released artifact. For OpenAPI specs there's a tool to compare two OpenAPI specs, it can be configured in many ways, but most importantly to check whether there is a breaking change. The tool can generate reports as Markdown and/or HTML, which is quite helpful. It doesn't require a lot of work or code to get that into the Polaris build. With both checks in place (Java and OpenAPI), it would be pretty safe to work "from the Java side" using Microprofile OpenAPI annotations, which BTW works nicely with Immutables. We can then even generate an OpenAPI spec from the Java types and still generate (other) Java code from that. Robert On Thu, Feb 12, 2026 at 5:04 PM Dmitri Bourlatchkov <[email protected]> wrote: > Hi All, > > I believe OpenAPI (REST) interface definitions that Polaris provides are > very useful for end users and machine clients. > > However, I see that server-side code generation leads to duplication > between generated code and hand-written code. For example, > `PolarisCatalogsApi` is generated, but most of the method signatures in > `PolarisServiceImpl` have to be written by hand to match the generated > code. > > I wonder what people think about using direct hand-written service classes > to connect to REST endpoints via Rs-Api (Jakarta) annotations? > > I can see that generating service stubs might appear helpful to ensure that > all API endpoints have code that matches OpenAPI specs. However, we have to > make tests to verify correct behaviour anyway. Those tests could be made > with a generated client and will automatically ensure correct hand-written > code assuming coverage is good. > > WDYT? > > Thanks, > Dmitri. >
