You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@polaris.apache.org by Dmitri Bourlatchkov <di...@apache.org> on 2026/02/12 16:03:39 UTC
[DISCUSS] Removing server-side OpenAPI code generation
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.
Re: [DISCUSS] Removing server-side OpenAPI code generation
Posted by Alexandre Dutra <ad...@apache.org>.
Hi all,
I think we now need some PoCs. It would be good to see what a
code-first approach would look like.
I also mentioned using different OpenAPI generators. I think I still
have an old branch with the "jaxrs-spec" generator that I mentioned
previously, I can open a PR for it if there is interest.
Thanks,
Alex
On Wed, Mar 4, 2026 at 11:42 PM Dmitri Bourlatchkov <di...@apache.org> wrote:
>
> Hi Michael,
>
> I probably was not very clear in my earlier messages :) sorry about the
> confusion.
>
> The way I see the OpenAPI tooling situation is that generating server-side
> code from the YAML spec ensures that URI paths and payload types /
> structures are compliant with the spec.
>
> On the other side of the coin, we have to manually write code to match the
> generated stubs. (side note: this reminds my of CORBA :disappear: )
>
> I find the latter part inconvenient from a human developer's perspective.
> Also, if we have to adjust stubs to leverage something specific from the
> platform (e.g. asynchronous processing), the (stub) code generation becomes
> more of an obstacle than a help.
>
> Now, going back to specific proposals, I was thinking about leveraging
> JaxRs annotations directly on hand-written endpoint implementation classes
> (basically the methods binding to @Path annotations) and avoiding generated
> server-side stubs. The code can still use generated classes for payload
> serialization. I believe this will remove a good chunk of boiler-plate
> code.
>
> WDYT?
>
> Cheers,
> Dmitri.
>
> On Tue, Mar 3, 2026 at 8:32 PM Michael Collado <co...@gmail.com>
> wrote:
>
> > Sorry for the late reply. I guess I'm not sure what your proposal is. You
> > are suggesting we go with the Java annotation-based approach and generate
> > the OpenAPI yaml from the Java code, right? That's the code-first (or
> > bottom-up) approach.
> >
> > I get the awkwardness of the spec-first approach, but IMO, it's less
> > awkward than having to reconcile two specs after the fact, which is what
> > we'd have to do in the bottom-up approach to ensure compliance with the
> > Iceberg spec. Yes, we have to run the tests anyway to ensure behavior is
> > correct, but runtime testing is both slower than compile-time checking and
> > also, IME, doesn't drive the actual development process like interface
> > changes do. E.g., optional parameters can simply be ignored during the
> > integration tests, whereas they actually cause someone to make a conscious
> > choice about handling them when the interface definition changes. One of
> > the alternative tools that validates spec compliance seems like it
> > would fill the gap, as Alex says, but TBH, I don't see the point. I guess I
> > just don't feel as awkward with the spec-first approach.
> >
> > As I mentioned, I'm not tied to any particular tool for the code
> > generation, so if there is an alternative that is less verbose or solve
> > some particular problem better, I'd be open to hear it, but as for
> > abandoning the code generation entirely, I feel there would need to be a
> > strong technical reason to go that route more than just "general
> > awkwardness".
> >
> > Mike
> >
> > On Tue, Feb 17, 2026 at 11:11 AM Dmitri Bourlatchkov <di...@apache.org>
> > wrote:
> >
> > > Hi Michael,
> > >
> > > I actually side with your sentiment about the spec-first approach, but
> > let
> > > me clarify my concern here.
> > >
> > > Specs should certainly be developed before implementation is finalized.
> > >
> > > However, automating server-side code generation from the OpenAPI yaml has
> > > some technical awkwardness (as I described in my fist email on this
> > > thread).
> > >
> > > The alternative I'm proposing here is to avoid the intermediate stub
> > > generation step and code endpoint implementation to match the existing
> > > Iceberg REST API spec by leverating annotations and support from the
> > > framework (Quarkus).
> > >
> > > I believe this approach provides more flexibility on the implementation
> > > side and the amount of hand-written code is roughly the same whether we
> > use
> > > generated stubs or not.
> > >
> > > Compliance with the Iceberg spec is to be validated by running TCK /
> > > Integration tests in CI. The integration tests could still use Iceberg
> > > OpenAPI yaml for generating clients in whatever language is convenient
> > for
> > > them. Compliance tests are required even with generated server stubs,
> > > because we cannot be completely sure the generated code is correct.
> > >
> > > Using different / more advanced tooling for server stub generation is
> > going
> > > to require more effort than manually adjusting java annotations to match
> > > Iceberg spec changes. My assessment of this is grounded in the fact that
> > > current hand-written code in Polaris has to adjust to spec changes in any
> > > case. Any behaviour changes will require a thought process to adjust
> > > server-side implementations, this part is hardly automatable in the
> > current
> > > Polaris build framework.
> > >
> > > When we're talking about Polaris' own APIs (Management, Generic Tables)
> > we
> > > could generate the Open API yaml from the endpoint annotations, as Robert
> > > suggested. With this approach we can still review and settle on the spec
> > > before implementation is plugged in. The only conceptual difference is
> > that
> > > the "source" for the spec will be code annotations (java) rather than
> > > OpenAPI yaml.
> > >
> > > That said, we can probably consider moving the spec "source" to java
> > > annotations as stage two, if the community is fine with removing
> > generated
> > > server stubs in general.
> > >
> > > WDYT?
> > >
> > > Thanks,
> > > Dmitri.
> > >
> > > On Sat, Feb 14, 2026 at 1:25 PM Michael Collado <co...@gmail.com>
> > > wrote:
> > >
> > > > While I’m not particular about the tools, I’m pretty strongly in favor
> > of
> > > > the spec first approach. While the management APIs have the freedom to
> > be
> > > > code-first, the Iceberg catalog APIs are subject to a spec outside of
> > our
> > > > control. Adding in tools later to ensure compatibility feels
> > > unnecessarily
> > > > complex and just adds another thing we have to know about and maintain.
> > > I’d
> > > > be in favor of evaluating simpler, less verbose generators.
> > > >
> > > > Mike
> > > >
> > > > On Fri, Feb 13, 2026 at 2:25 PM Romain Manni-Bucau <
> > > rmannibucau@gmail.com>
> > > > wrote:
> > > >
> > > > > What about moving to JSON-B? 🤔
> > > > > I know it can look like it misses fun feature but there is no
> > technical
> > > > > reason you don't manage to do all you want with it.
> > > > > Will be more consistent with microprofile and more future friendly
> > IMHO
> > > > for
> > > > > the project.
> > > > >
> > > > > Romain Manni-Bucau
> > > > > @rmannibucau <https://x.com/rmannibucau> | .NET Blog
> > > > > <https://dotnetbirdie.github.io/> | Blog <
> > > https://rmannibucau.github.io/
> > > > >
> > > > > | Old
> > > > > Blog <http://rmannibucau.wordpress.com> | Github
> > > > > <https://github.com/rmannibucau> | LinkedIn
> > > > > <https://www.linkedin.com/in/rmannibucau> | Book
> > > > > <
> > > > >
> > > >
> > >
> > https://www.packtpub.com/en-us/product/java-ee-8-high-performance-9781788473064
> > > > > >
> > > > > Javaccino founder (Java/.NET service - contact via linkedin)
> > > > >
> > > > >
> > > > > Le ven. 13 févr. 2026 à 16:03, Alexandre Dutra <ad...@apache.org> a
> > > > > écrit :
> > > > >
> > > > > > Hi Robert,
> > > > > >
> > > > > > Good point about Jackson 3, I agree that we should migrate ahead of
> > > > > > Quarkus if possible, and that a code-first approach would make
> > things
> > > > > > easier.
> > > > > >
> > > > > > That said, it seems that support for Jackson 3 is now deferred to
> > > > Quarkus
> > > > > > 4 [1].
> > > > > >
> > > > > > Thanks,
> > > > > > Alex
> > > > > >
> > > > > > [1]: https://github.com/quarkusio/quarkus/issues/52036
> > > > > >
> > > > > > On Fri, Feb 13, 2026 at 3:18 PM Robert Stupp <sn...@snazy.de>
> > wrote:
> > > > > > >
> > > > > > > Another aspect, although strictly speaking unrelated, is Jackson
> > 3.
> > > > All
> > > > > > > custom Jackson 2 serializers are incompatible with Jackson 3, and
> > > > some
> > > > > > > annotations are different. It is possible to use both Jackson 2
> > + 3
> > > > > > > annotations in the "code first" approach, and it works fine with
> > > > > > Immutables.
> > > > > > >
> > > > > > > I'd expect Jackson 3 to become a necessity in the near future.
> > For
> > > > > > Quarkus,
> > > > > > > it was already on the list of ideas for 3.31, but thankfully
> > moved
> > > > out.
> > > > > > > A "code first" approach would save us that headache in the JAX-RS
> > > > > > context.
> > > > > > >
> > > > > > > Side note: it's possible to use both Jackson 2 and Jackson 3 in
> > the
> > > > > same
> > > > > > > code base - they can work side by side.
> > > > > > >
> > > > > > >
> > > > > > > On Fri, Feb 13, 2026 at 3:00 PM Jean-Baptiste Onofré <
> > > > jb@nanthrax.net>
> > > > > > > wrote:
> > > > > > >
> > > > > > > > Hi Dmitri,
> > > > > > > >
> > > > > > > > Thanks for starting this discussion.
> > > > > > > >
> > > > > > > > While I have a preference for the code-first approach, I wonder
> > > if
> > > > we
> > > > > > can
> > > > > > > > easily support the Iceberg REST Spec using this method. I would
> > > > like
> > > > > > to use
> > > > > > > > JaxRS annotations, but it might be tricky to cleanly leverage
> > the
> > > > > > Iceberg
> > > > > > > > REST Spec.
> > > > > > > >
> > > > > > > > Just my $0.01
> > > > > > > >
> > > > > > > > Regards,
> > > > > > > > JB
> > > > > > > >
> > > > > > > > On Thu, Feb 12, 2026 at 5:04 PM Dmitri Bourlatchkov <
> > > > > dimas@apache.org>
> > > > > > > > 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.
> > > > > > > > >
> > > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
Re: [DISCUSS] Removing server-side OpenAPI code generation
Posted by Dmitri Bourlatchkov <di...@apache.org>.
Hi Michael,
I probably was not very clear in my earlier messages :) sorry about the
confusion.
The way I see the OpenAPI tooling situation is that generating server-side
code from the YAML spec ensures that URI paths and payload types /
structures are compliant with the spec.
On the other side of the coin, we have to manually write code to match the
generated stubs. (side note: this reminds my of CORBA :disappear: )
I find the latter part inconvenient from a human developer's perspective.
Also, if we have to adjust stubs to leverage something specific from the
platform (e.g. asynchronous processing), the (stub) code generation becomes
more of an obstacle than a help.
Now, going back to specific proposals, I was thinking about leveraging
JaxRs annotations directly on hand-written endpoint implementation classes
(basically the methods binding to @Path annotations) and avoiding generated
server-side stubs. The code can still use generated classes for payload
serialization. I believe this will remove a good chunk of boiler-plate
code.
WDYT?
Cheers,
Dmitri.
On Tue, Mar 3, 2026 at 8:32 PM Michael Collado <co...@gmail.com>
wrote:
> Sorry for the late reply. I guess I'm not sure what your proposal is. You
> are suggesting we go with the Java annotation-based approach and generate
> the OpenAPI yaml from the Java code, right? That's the code-first (or
> bottom-up) approach.
>
> I get the awkwardness of the spec-first approach, but IMO, it's less
> awkward than having to reconcile two specs after the fact, which is what
> we'd have to do in the bottom-up approach to ensure compliance with the
> Iceberg spec. Yes, we have to run the tests anyway to ensure behavior is
> correct, but runtime testing is both slower than compile-time checking and
> also, IME, doesn't drive the actual development process like interface
> changes do. E.g., optional parameters can simply be ignored during the
> integration tests, whereas they actually cause someone to make a conscious
> choice about handling them when the interface definition changes. One of
> the alternative tools that validates spec compliance seems like it
> would fill the gap, as Alex says, but TBH, I don't see the point. I guess I
> just don't feel as awkward with the spec-first approach.
>
> As I mentioned, I'm not tied to any particular tool for the code
> generation, so if there is an alternative that is less verbose or solve
> some particular problem better, I'd be open to hear it, but as for
> abandoning the code generation entirely, I feel there would need to be a
> strong technical reason to go that route more than just "general
> awkwardness".
>
> Mike
>
> On Tue, Feb 17, 2026 at 11:11 AM Dmitri Bourlatchkov <di...@apache.org>
> wrote:
>
> > Hi Michael,
> >
> > I actually side with your sentiment about the spec-first approach, but
> let
> > me clarify my concern here.
> >
> > Specs should certainly be developed before implementation is finalized.
> >
> > However, automating server-side code generation from the OpenAPI yaml has
> > some technical awkwardness (as I described in my fist email on this
> > thread).
> >
> > The alternative I'm proposing here is to avoid the intermediate stub
> > generation step and code endpoint implementation to match the existing
> > Iceberg REST API spec by leverating annotations and support from the
> > framework (Quarkus).
> >
> > I believe this approach provides more flexibility on the implementation
> > side and the amount of hand-written code is roughly the same whether we
> use
> > generated stubs or not.
> >
> > Compliance with the Iceberg spec is to be validated by running TCK /
> > Integration tests in CI. The integration tests could still use Iceberg
> > OpenAPI yaml for generating clients in whatever language is convenient
> for
> > them. Compliance tests are required even with generated server stubs,
> > because we cannot be completely sure the generated code is correct.
> >
> > Using different / more advanced tooling for server stub generation is
> going
> > to require more effort than manually adjusting java annotations to match
> > Iceberg spec changes. My assessment of this is grounded in the fact that
> > current hand-written code in Polaris has to adjust to spec changes in any
> > case. Any behaviour changes will require a thought process to adjust
> > server-side implementations, this part is hardly automatable in the
> current
> > Polaris build framework.
> >
> > When we're talking about Polaris' own APIs (Management, Generic Tables)
> we
> > could generate the Open API yaml from the endpoint annotations, as Robert
> > suggested. With this approach we can still review and settle on the spec
> > before implementation is plugged in. The only conceptual difference is
> that
> > the "source" for the spec will be code annotations (java) rather than
> > OpenAPI yaml.
> >
> > That said, we can probably consider moving the spec "source" to java
> > annotations as stage two, if the community is fine with removing
> generated
> > server stubs in general.
> >
> > WDYT?
> >
> > Thanks,
> > Dmitri.
> >
> > On Sat, Feb 14, 2026 at 1:25 PM Michael Collado <co...@gmail.com>
> > wrote:
> >
> > > While I’m not particular about the tools, I’m pretty strongly in favor
> of
> > > the spec first approach. While the management APIs have the freedom to
> be
> > > code-first, the Iceberg catalog APIs are subject to a spec outside of
> our
> > > control. Adding in tools later to ensure compatibility feels
> > unnecessarily
> > > complex and just adds another thing we have to know about and maintain.
> > I’d
> > > be in favor of evaluating simpler, less verbose generators.
> > >
> > > Mike
> > >
> > > On Fri, Feb 13, 2026 at 2:25 PM Romain Manni-Bucau <
> > rmannibucau@gmail.com>
> > > wrote:
> > >
> > > > What about moving to JSON-B? 🤔
> > > > I know it can look like it misses fun feature but there is no
> technical
> > > > reason you don't manage to do all you want with it.
> > > > Will be more consistent with microprofile and more future friendly
> IMHO
> > > for
> > > > the project.
> > > >
> > > > Romain Manni-Bucau
> > > > @rmannibucau <https://x.com/rmannibucau> | .NET Blog
> > > > <https://dotnetbirdie.github.io/> | Blog <
> > https://rmannibucau.github.io/
> > > >
> > > > | Old
> > > > Blog <http://rmannibucau.wordpress.com> | Github
> > > > <https://github.com/rmannibucau> | LinkedIn
> > > > <https://www.linkedin.com/in/rmannibucau> | Book
> > > > <
> > > >
> > >
> >
> https://www.packtpub.com/en-us/product/java-ee-8-high-performance-9781788473064
> > > > >
> > > > Javaccino founder (Java/.NET service - contact via linkedin)
> > > >
> > > >
> > > > Le ven. 13 févr. 2026 à 16:03, Alexandre Dutra <ad...@apache.org> a
> > > > écrit :
> > > >
> > > > > Hi Robert,
> > > > >
> > > > > Good point about Jackson 3, I agree that we should migrate ahead of
> > > > > Quarkus if possible, and that a code-first approach would make
> things
> > > > > easier.
> > > > >
> > > > > That said, it seems that support for Jackson 3 is now deferred to
> > > Quarkus
> > > > > 4 [1].
> > > > >
> > > > > Thanks,
> > > > > Alex
> > > > >
> > > > > [1]: https://github.com/quarkusio/quarkus/issues/52036
> > > > >
> > > > > On Fri, Feb 13, 2026 at 3:18 PM Robert Stupp <sn...@snazy.de>
> wrote:
> > > > > >
> > > > > > Another aspect, although strictly speaking unrelated, is Jackson
> 3.
> > > All
> > > > > > custom Jackson 2 serializers are incompatible with Jackson 3, and
> > > some
> > > > > > annotations are different. It is possible to use both Jackson 2
> + 3
> > > > > > annotations in the "code first" approach, and it works fine with
> > > > > Immutables.
> > > > > >
> > > > > > I'd expect Jackson 3 to become a necessity in the near future.
> For
> > > > > Quarkus,
> > > > > > it was already on the list of ideas for 3.31, but thankfully
> moved
> > > out.
> > > > > > A "code first" approach would save us that headache in the JAX-RS
> > > > > context.
> > > > > >
> > > > > > Side note: it's possible to use both Jackson 2 and Jackson 3 in
> the
> > > > same
> > > > > > code base - they can work side by side.
> > > > > >
> > > > > >
> > > > > > On Fri, Feb 13, 2026 at 3:00 PM Jean-Baptiste Onofré <
> > > jb@nanthrax.net>
> > > > > > wrote:
> > > > > >
> > > > > > > Hi Dmitri,
> > > > > > >
> > > > > > > Thanks for starting this discussion.
> > > > > > >
> > > > > > > While I have a preference for the code-first approach, I wonder
> > if
> > > we
> > > > > can
> > > > > > > easily support the Iceberg REST Spec using this method. I would
> > > like
> > > > > to use
> > > > > > > JaxRS annotations, but it might be tricky to cleanly leverage
> the
> > > > > Iceberg
> > > > > > > REST Spec.
> > > > > > >
> > > > > > > Just my $0.01
> > > > > > >
> > > > > > > Regards,
> > > > > > > JB
> > > > > > >
> > > > > > > On Thu, Feb 12, 2026 at 5:04 PM Dmitri Bourlatchkov <
> > > > dimas@apache.org>
> > > > > > > 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.
> > > > > > > >
> > > > > > >
> > > > >
> > > >
> > >
> >
>
Re: [DISCUSS] Removing server-side OpenAPI code generation
Posted by Michael Collado <co...@gmail.com>.
Sorry for the late reply. I guess I'm not sure what your proposal is. You
are suggesting we go with the Java annotation-based approach and generate
the OpenAPI yaml from the Java code, right? That's the code-first (or
bottom-up) approach.
I get the awkwardness of the spec-first approach, but IMO, it's less
awkward than having to reconcile two specs after the fact, which is what
we'd have to do in the bottom-up approach to ensure compliance with the
Iceberg spec. Yes, we have to run the tests anyway to ensure behavior is
correct, but runtime testing is both slower than compile-time checking and
also, IME, doesn't drive the actual development process like interface
changes do. E.g., optional parameters can simply be ignored during the
integration tests, whereas they actually cause someone to make a conscious
choice about handling them when the interface definition changes. One of
the alternative tools that validates spec compliance seems like it
would fill the gap, as Alex says, but TBH, I don't see the point. I guess I
just don't feel as awkward with the spec-first approach.
As I mentioned, I'm not tied to any particular tool for the code
generation, so if there is an alternative that is less verbose or solve
some particular problem better, I'd be open to hear it, but as for
abandoning the code generation entirely, I feel there would need to be a
strong technical reason to go that route more than just "general
awkwardness".
Mike
On Tue, Feb 17, 2026 at 11:11 AM Dmitri Bourlatchkov <di...@apache.org>
wrote:
> Hi Michael,
>
> I actually side with your sentiment about the spec-first approach, but let
> me clarify my concern here.
>
> Specs should certainly be developed before implementation is finalized.
>
> However, automating server-side code generation from the OpenAPI yaml has
> some technical awkwardness (as I described in my fist email on this
> thread).
>
> The alternative I'm proposing here is to avoid the intermediate stub
> generation step and code endpoint implementation to match the existing
> Iceberg REST API spec by leverating annotations and support from the
> framework (Quarkus).
>
> I believe this approach provides more flexibility on the implementation
> side and the amount of hand-written code is roughly the same whether we use
> generated stubs or not.
>
> Compliance with the Iceberg spec is to be validated by running TCK /
> Integration tests in CI. The integration tests could still use Iceberg
> OpenAPI yaml for generating clients in whatever language is convenient for
> them. Compliance tests are required even with generated server stubs,
> because we cannot be completely sure the generated code is correct.
>
> Using different / more advanced tooling for server stub generation is going
> to require more effort than manually adjusting java annotations to match
> Iceberg spec changes. My assessment of this is grounded in the fact that
> current hand-written code in Polaris has to adjust to spec changes in any
> case. Any behaviour changes will require a thought process to adjust
> server-side implementations, this part is hardly automatable in the current
> Polaris build framework.
>
> When we're talking about Polaris' own APIs (Management, Generic Tables) we
> could generate the Open API yaml from the endpoint annotations, as Robert
> suggested. With this approach we can still review and settle on the spec
> before implementation is plugged in. The only conceptual difference is that
> the "source" for the spec will be code annotations (java) rather than
> OpenAPI yaml.
>
> That said, we can probably consider moving the spec "source" to java
> annotations as stage two, if the community is fine with removing generated
> server stubs in general.
>
> WDYT?
>
> Thanks,
> Dmitri.
>
> On Sat, Feb 14, 2026 at 1:25 PM Michael Collado <co...@gmail.com>
> wrote:
>
> > While I’m not particular about the tools, I’m pretty strongly in favor of
> > the spec first approach. While the management APIs have the freedom to be
> > code-first, the Iceberg catalog APIs are subject to a spec outside of our
> > control. Adding in tools later to ensure compatibility feels
> unnecessarily
> > complex and just adds another thing we have to know about and maintain.
> I’d
> > be in favor of evaluating simpler, less verbose generators.
> >
> > Mike
> >
> > On Fri, Feb 13, 2026 at 2:25 PM Romain Manni-Bucau <
> rmannibucau@gmail.com>
> > wrote:
> >
> > > What about moving to JSON-B? 🤔
> > > I know it can look like it misses fun feature but there is no technical
> > > reason you don't manage to do all you want with it.
> > > Will be more consistent with microprofile and more future friendly IMHO
> > for
> > > the project.
> > >
> > > Romain Manni-Bucau
> > > @rmannibucau <https://x.com/rmannibucau> | .NET Blog
> > > <https://dotnetbirdie.github.io/> | Blog <
> https://rmannibucau.github.io/
> > >
> > > | Old
> > > Blog <http://rmannibucau.wordpress.com> | Github
> > > <https://github.com/rmannibucau> | LinkedIn
> > > <https://www.linkedin.com/in/rmannibucau> | Book
> > > <
> > >
> >
> https://www.packtpub.com/en-us/product/java-ee-8-high-performance-9781788473064
> > > >
> > > Javaccino founder (Java/.NET service - contact via linkedin)
> > >
> > >
> > > Le ven. 13 févr. 2026 à 16:03, Alexandre Dutra <ad...@apache.org> a
> > > écrit :
> > >
> > > > Hi Robert,
> > > >
> > > > Good point about Jackson 3, I agree that we should migrate ahead of
> > > > Quarkus if possible, and that a code-first approach would make things
> > > > easier.
> > > >
> > > > That said, it seems that support for Jackson 3 is now deferred to
> > Quarkus
> > > > 4 [1].
> > > >
> > > > Thanks,
> > > > Alex
> > > >
> > > > [1]: https://github.com/quarkusio/quarkus/issues/52036
> > > >
> > > > On Fri, Feb 13, 2026 at 3:18 PM Robert Stupp <sn...@snazy.de> wrote:
> > > > >
> > > > > Another aspect, although strictly speaking unrelated, is Jackson 3.
> > All
> > > > > custom Jackson 2 serializers are incompatible with Jackson 3, and
> > some
> > > > > annotations are different. It is possible to use both Jackson 2 + 3
> > > > > annotations in the "code first" approach, and it works fine with
> > > > Immutables.
> > > > >
> > > > > I'd expect Jackson 3 to become a necessity in the near future. For
> > > > Quarkus,
> > > > > it was already on the list of ideas for 3.31, but thankfully moved
> > out.
> > > > > A "code first" approach would save us that headache in the JAX-RS
> > > > context.
> > > > >
> > > > > Side note: it's possible to use both Jackson 2 and Jackson 3 in the
> > > same
> > > > > code base - they can work side by side.
> > > > >
> > > > >
> > > > > On Fri, Feb 13, 2026 at 3:00 PM Jean-Baptiste Onofré <
> > jb@nanthrax.net>
> > > > > wrote:
> > > > >
> > > > > > Hi Dmitri,
> > > > > >
> > > > > > Thanks for starting this discussion.
> > > > > >
> > > > > > While I have a preference for the code-first approach, I wonder
> if
> > we
> > > > can
> > > > > > easily support the Iceberg REST Spec using this method. I would
> > like
> > > > to use
> > > > > > JaxRS annotations, but it might be tricky to cleanly leverage the
> > > > Iceberg
> > > > > > REST Spec.
> > > > > >
> > > > > > Just my $0.01
> > > > > >
> > > > > > Regards,
> > > > > > JB
> > > > > >
> > > > > > On Thu, Feb 12, 2026 at 5:04 PM Dmitri Bourlatchkov <
> > > dimas@apache.org>
> > > > > > 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.
> > > > > > >
> > > > > >
> > > >
> > >
> >
>
Re: [DISCUSS] Removing server-side OpenAPI code generation
Posted by Dmitri Bourlatchkov <di...@apache.org>.
Hi Michael,
I actually side with your sentiment about the spec-first approach, but let
me clarify my concern here.
Specs should certainly be developed before implementation is finalized.
However, automating server-side code generation from the OpenAPI yaml has
some technical awkwardness (as I described in my fist email on this thread).
The alternative I'm proposing here is to avoid the intermediate stub
generation step and code endpoint implementation to match the existing
Iceberg REST API spec by leverating annotations and support from the
framework (Quarkus).
I believe this approach provides more flexibility on the implementation
side and the amount of hand-written code is roughly the same whether we use
generated stubs or not.
Compliance with the Iceberg spec is to be validated by running TCK /
Integration tests in CI. The integration tests could still use Iceberg
OpenAPI yaml for generating clients in whatever language is convenient for
them. Compliance tests are required even with generated server stubs,
because we cannot be completely sure the generated code is correct.
Using different / more advanced tooling for server stub generation is going
to require more effort than manually adjusting java annotations to match
Iceberg spec changes. My assessment of this is grounded in the fact that
current hand-written code in Polaris has to adjust to spec changes in any
case. Any behaviour changes will require a thought process to adjust
server-side implementations, this part is hardly automatable in the current
Polaris build framework.
When we're talking about Polaris' own APIs (Management, Generic Tables) we
could generate the Open API yaml from the endpoint annotations, as Robert
suggested. With this approach we can still review and settle on the spec
before implementation is plugged in. The only conceptual difference is that
the "source" for the spec will be code annotations (java) rather than
OpenAPI yaml.
That said, we can probably consider moving the spec "source" to java
annotations as stage two, if the community is fine with removing generated
server stubs in general.
WDYT?
Thanks,
Dmitri.
On Sat, Feb 14, 2026 at 1:25 PM Michael Collado <co...@gmail.com>
wrote:
> While I’m not particular about the tools, I’m pretty strongly in favor of
> the spec first approach. While the management APIs have the freedom to be
> code-first, the Iceberg catalog APIs are subject to a spec outside of our
> control. Adding in tools later to ensure compatibility feels unnecessarily
> complex and just adds another thing we have to know about and maintain. I’d
> be in favor of evaluating simpler, less verbose generators.
>
> Mike
>
> On Fri, Feb 13, 2026 at 2:25 PM Romain Manni-Bucau <rm...@gmail.com>
> wrote:
>
> > What about moving to JSON-B? 🤔
> > I know it can look like it misses fun feature but there is no technical
> > reason you don't manage to do all you want with it.
> > Will be more consistent with microprofile and more future friendly IMHO
> for
> > the project.
> >
> > Romain Manni-Bucau
> > @rmannibucau <https://x.com/rmannibucau> | .NET Blog
> > <https://dotnetbirdie.github.io/> | Blog <https://rmannibucau.github.io/
> >
> > | Old
> > Blog <http://rmannibucau.wordpress.com> | Github
> > <https://github.com/rmannibucau> | LinkedIn
> > <https://www.linkedin.com/in/rmannibucau> | Book
> > <
> >
> https://www.packtpub.com/en-us/product/java-ee-8-high-performance-9781788473064
> > >
> > Javaccino founder (Java/.NET service - contact via linkedin)
> >
> >
> > Le ven. 13 févr. 2026 à 16:03, Alexandre Dutra <ad...@apache.org> a
> > écrit :
> >
> > > Hi Robert,
> > >
> > > Good point about Jackson 3, I agree that we should migrate ahead of
> > > Quarkus if possible, and that a code-first approach would make things
> > > easier.
> > >
> > > That said, it seems that support for Jackson 3 is now deferred to
> Quarkus
> > > 4 [1].
> > >
> > > Thanks,
> > > Alex
> > >
> > > [1]: https://github.com/quarkusio/quarkus/issues/52036
> > >
> > > On Fri, Feb 13, 2026 at 3:18 PM Robert Stupp <sn...@snazy.de> wrote:
> > > >
> > > > Another aspect, although strictly speaking unrelated, is Jackson 3.
> All
> > > > custom Jackson 2 serializers are incompatible with Jackson 3, and
> some
> > > > annotations are different. It is possible to use both Jackson 2 + 3
> > > > annotations in the "code first" approach, and it works fine with
> > > Immutables.
> > > >
> > > > I'd expect Jackson 3 to become a necessity in the near future. For
> > > Quarkus,
> > > > it was already on the list of ideas for 3.31, but thankfully moved
> out.
> > > > A "code first" approach would save us that headache in the JAX-RS
> > > context.
> > > >
> > > > Side note: it's possible to use both Jackson 2 and Jackson 3 in the
> > same
> > > > code base - they can work side by side.
> > > >
> > > >
> > > > On Fri, Feb 13, 2026 at 3:00 PM Jean-Baptiste Onofré <
> jb@nanthrax.net>
> > > > wrote:
> > > >
> > > > > Hi Dmitri,
> > > > >
> > > > > Thanks for starting this discussion.
> > > > >
> > > > > While I have a preference for the code-first approach, I wonder if
> we
> > > can
> > > > > easily support the Iceberg REST Spec using this method. I would
> like
> > > to use
> > > > > JaxRS annotations, but it might be tricky to cleanly leverage the
> > > Iceberg
> > > > > REST Spec.
> > > > >
> > > > > Just my $0.01
> > > > >
> > > > > Regards,
> > > > > JB
> > > > >
> > > > > On Thu, Feb 12, 2026 at 5:04 PM Dmitri Bourlatchkov <
> > dimas@apache.org>
> > > > > 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.
> > > > > >
> > > > >
> > >
> >
>
Re: [DISCUSS] Removing server-side OpenAPI code generation
Posted by Michael Collado <co...@gmail.com>.
While I’m not particular about the tools, I’m pretty strongly in favor of
the spec first approach. While the management APIs have the freedom to be
code-first, the Iceberg catalog APIs are subject to a spec outside of our
control. Adding in tools later to ensure compatibility feels unnecessarily
complex and just adds another thing we have to know about and maintain. I’d
be in favor of evaluating simpler, less verbose generators.
Mike
On Fri, Feb 13, 2026 at 2:25 PM Romain Manni-Bucau <rm...@gmail.com>
wrote:
> What about moving to JSON-B? 🤔
> I know it can look like it misses fun feature but there is no technical
> reason you don't manage to do all you want with it.
> Will be more consistent with microprofile and more future friendly IMHO for
> the project.
>
> Romain Manni-Bucau
> @rmannibucau <https://x.com/rmannibucau> | .NET Blog
> <https://dotnetbirdie.github.io/> | Blog <https://rmannibucau.github.io/>
> | Old
> Blog <http://rmannibucau.wordpress.com> | Github
> <https://github.com/rmannibucau> | LinkedIn
> <https://www.linkedin.com/in/rmannibucau> | Book
> <
> https://www.packtpub.com/en-us/product/java-ee-8-high-performance-9781788473064
> >
> Javaccino founder (Java/.NET service - contact via linkedin)
>
>
> Le ven. 13 févr. 2026 à 16:03, Alexandre Dutra <ad...@apache.org> a
> écrit :
>
> > Hi Robert,
> >
> > Good point about Jackson 3, I agree that we should migrate ahead of
> > Quarkus if possible, and that a code-first approach would make things
> > easier.
> >
> > That said, it seems that support for Jackson 3 is now deferred to Quarkus
> > 4 [1].
> >
> > Thanks,
> > Alex
> >
> > [1]: https://github.com/quarkusio/quarkus/issues/52036
> >
> > On Fri, Feb 13, 2026 at 3:18 PM Robert Stupp <sn...@snazy.de> wrote:
> > >
> > > Another aspect, although strictly speaking unrelated, is Jackson 3. All
> > > custom Jackson 2 serializers are incompatible with Jackson 3, and some
> > > annotations are different. It is possible to use both Jackson 2 + 3
> > > annotations in the "code first" approach, and it works fine with
> > Immutables.
> > >
> > > I'd expect Jackson 3 to become a necessity in the near future. For
> > Quarkus,
> > > it was already on the list of ideas for 3.31, but thankfully moved out.
> > > A "code first" approach would save us that headache in the JAX-RS
> > context.
> > >
> > > Side note: it's possible to use both Jackson 2 and Jackson 3 in the
> same
> > > code base - they can work side by side.
> > >
> > >
> > > On Fri, Feb 13, 2026 at 3:00 PM Jean-Baptiste Onofré <jb...@nanthrax.net>
> > > wrote:
> > >
> > > > Hi Dmitri,
> > > >
> > > > Thanks for starting this discussion.
> > > >
> > > > While I have a preference for the code-first approach, I wonder if we
> > can
> > > > easily support the Iceberg REST Spec using this method. I would like
> > to use
> > > > JaxRS annotations, but it might be tricky to cleanly leverage the
> > Iceberg
> > > > REST Spec.
> > > >
> > > > Just my $0.01
> > > >
> > > > Regards,
> > > > JB
> > > >
> > > > On Thu, Feb 12, 2026 at 5:04 PM Dmitri Bourlatchkov <
> dimas@apache.org>
> > > > 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.
> > > > >
> > > >
> >
>
Re: [DISCUSS] Removing server-side OpenAPI code generation
Posted by Romain Manni-Bucau <rm...@gmail.com>.
What about moving to JSON-B? 🤔
I know it can look like it misses fun feature but there is no technical
reason you don't manage to do all you want with it.
Will be more consistent with microprofile and more future friendly IMHO for
the project.
Romain Manni-Bucau
@rmannibucau <https://x.com/rmannibucau> | .NET Blog
<https://dotnetbirdie.github.io/> | Blog <https://rmannibucau.github.io/> | Old
Blog <http://rmannibucau.wordpress.com> | Github
<https://github.com/rmannibucau> | LinkedIn
<https://www.linkedin.com/in/rmannibucau> | Book
<https://www.packtpub.com/en-us/product/java-ee-8-high-performance-9781788473064>
Javaccino founder (Java/.NET service - contact via linkedin)
Le ven. 13 févr. 2026 à 16:03, Alexandre Dutra <ad...@apache.org> a écrit :
> Hi Robert,
>
> Good point about Jackson 3, I agree that we should migrate ahead of
> Quarkus if possible, and that a code-first approach would make things
> easier.
>
> That said, it seems that support for Jackson 3 is now deferred to Quarkus
> 4 [1].
>
> Thanks,
> Alex
>
> [1]: https://github.com/quarkusio/quarkus/issues/52036
>
> On Fri, Feb 13, 2026 at 3:18 PM Robert Stupp <sn...@snazy.de> wrote:
> >
> > Another aspect, although strictly speaking unrelated, is Jackson 3. All
> > custom Jackson 2 serializers are incompatible with Jackson 3, and some
> > annotations are different. It is possible to use both Jackson 2 + 3
> > annotations in the "code first" approach, and it works fine with
> Immutables.
> >
> > I'd expect Jackson 3 to become a necessity in the near future. For
> Quarkus,
> > it was already on the list of ideas for 3.31, but thankfully moved out.
> > A "code first" approach would save us that headache in the JAX-RS
> context.
> >
> > Side note: it's possible to use both Jackson 2 and Jackson 3 in the same
> > code base - they can work side by side.
> >
> >
> > On Fri, Feb 13, 2026 at 3:00 PM Jean-Baptiste Onofré <jb...@nanthrax.net>
> > wrote:
> >
> > > Hi Dmitri,
> > >
> > > Thanks for starting this discussion.
> > >
> > > While I have a preference for the code-first approach, I wonder if we
> can
> > > easily support the Iceberg REST Spec using this method. I would like
> to use
> > > JaxRS annotations, but it might be tricky to cleanly leverage the
> Iceberg
> > > REST Spec.
> > >
> > > Just my $0.01
> > >
> > > Regards,
> > > JB
> > >
> > > On Thu, Feb 12, 2026 at 5:04 PM Dmitri Bourlatchkov <di...@apache.org>
> > > 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.
> > > >
> > >
>
Re: [DISCUSS] Removing server-side OpenAPI code generation
Posted by Alexandre Dutra <ad...@apache.org>.
Hi Robert,
Good point about Jackson 3, I agree that we should migrate ahead of
Quarkus if possible, and that a code-first approach would make things
easier.
That said, it seems that support for Jackson 3 is now deferred to Quarkus 4 [1].
Thanks,
Alex
[1]: https://github.com/quarkusio/quarkus/issues/52036
On Fri, Feb 13, 2026 at 3:18 PM Robert Stupp <sn...@snazy.de> wrote:
>
> Another aspect, although strictly speaking unrelated, is Jackson 3. All
> custom Jackson 2 serializers are incompatible with Jackson 3, and some
> annotations are different. It is possible to use both Jackson 2 + 3
> annotations in the "code first" approach, and it works fine with Immutables.
>
> I'd expect Jackson 3 to become a necessity in the near future. For Quarkus,
> it was already on the list of ideas for 3.31, but thankfully moved out.
> A "code first" approach would save us that headache in the JAX-RS context.
>
> Side note: it's possible to use both Jackson 2 and Jackson 3 in the same
> code base - they can work side by side.
>
>
> On Fri, Feb 13, 2026 at 3:00 PM Jean-Baptiste Onofré <jb...@nanthrax.net>
> wrote:
>
> > Hi Dmitri,
> >
> > Thanks for starting this discussion.
> >
> > While I have a preference for the code-first approach, I wonder if we can
> > easily support the Iceberg REST Spec using this method. I would like to use
> > JaxRS annotations, but it might be tricky to cleanly leverage the Iceberg
> > REST Spec.
> >
> > Just my $0.01
> >
> > Regards,
> > JB
> >
> > On Thu, Feb 12, 2026 at 5:04 PM Dmitri Bourlatchkov <di...@apache.org>
> > 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.
> > >
> >
Re: [DISCUSS] Removing server-side OpenAPI code generation
Posted by Robert Stupp <sn...@snazy.de>.
Another aspect, although strictly speaking unrelated, is Jackson 3. All
custom Jackson 2 serializers are incompatible with Jackson 3, and some
annotations are different. It is possible to use both Jackson 2 + 3
annotations in the "code first" approach, and it works fine with Immutables.
I'd expect Jackson 3 to become a necessity in the near future. For Quarkus,
it was already on the list of ideas for 3.31, but thankfully moved out.
A "code first" approach would save us that headache in the JAX-RS context.
Side note: it's possible to use both Jackson 2 and Jackson 3 in the same
code base - they can work side by side.
On Fri, Feb 13, 2026 at 3:00 PM Jean-Baptiste Onofré <jb...@nanthrax.net>
wrote:
> Hi Dmitri,
>
> Thanks for starting this discussion.
>
> While I have a preference for the code-first approach, I wonder if we can
> easily support the Iceberg REST Spec using this method. I would like to use
> JaxRS annotations, but it might be tricky to cleanly leverage the Iceberg
> REST Spec.
>
> Just my $0.01
>
> Regards,
> JB
>
> On Thu, Feb 12, 2026 at 5:04 PM Dmitri Bourlatchkov <di...@apache.org>
> 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.
> >
>
Re: [DISCUSS] Removing server-side OpenAPI code generation
Posted by Jean-Baptiste Onofré <jb...@nanthrax.net>.
Hi Dmitri,
Thanks for starting this discussion.
While I have a preference for the code-first approach, I wonder if we can
easily support the Iceberg REST Spec using this method. I would like to use
JaxRS annotations, but it might be tricky to cleanly leverage the Iceberg
REST Spec.
Just my $0.01
Regards,
JB
On Thu, Feb 12, 2026 at 5:04 PM Dmitri Bourlatchkov <di...@apache.org>
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.
>
Re: [DISCUSS] Removing server-side OpenAPI code generation
Posted by Alexandre Dutra <ad...@apache.org>.
Hi all,
The fundamental question here is whether we want a top-down or
bottom-up approach to the REST API.
The bottom-up approach (or code-first, if you prefer) is appealing for
many reasons, one of them being that we would be free to progressively
migrate Polaris to an asynchronous/reactive execution model.
But it also has its drawbacks, the biggest one being that we must
comply with Iceberg's REST spec. This is easily achievable in a
top-down approach – not so much in a bottom-up one. Both Robert's tool
[1] and Dmitri's suggestion of specific tests with a generated client
are good ways to fill the gap.
I'm slightly in favor of the bottom-up approach, but playing devil's
advocate, we could also explore the idea of keeping the top-down
approach, but generating less code. We use a rather verbose generator
today: "jaxrs-resteasy" (and with many custom templates). There are
other generators that would generate e.g only the REST interface, and
nothing else, e.g. the "jaxrs-spec" generator.
Also, the polaris-api-management-model module today is entirely
generated, but I think it could be made "code-first" even if we keep
the top-down approach, since it only generates "model" classes – we
could just as well write those pojos/records by hand.
Just my 2 cents.
Thanks,
Alex
[1]: https://github.com/apache/polaris/pull/3752
On Thu, Feb 12, 2026 at 9:13 PM Yufei Gu <fl...@gmail.com> wrote:
>
> I don't have a strong opinion on either side. I think the hand-written or
> ai-writtern gives us more controls and less duplicates, we may just go with
> it.
> Yufei
>
>
> On Thu, Feb 12, 2026 at 8:53 AM Romain Manni-Bucau <rm...@gmail.com>
> wrote:
>
> > Hi
> >
> > +1 to be java first while it doesn't reach the runtime since it is totally
> > useless to have these annotations, it must stay a build time generation and
> > potentially the runtime can manipulate the openapi.json if needed (almost
> > never but can be to filter by role).
> >
> > Romain Manni-Bucau
> > @rmannibucau <https://x.com/rmannibucau> | .NET Blog
> > <https://dotnetbirdie.github.io/> | Blog <https://rmannibucau.github.io/>
> > | Old
> > Blog <http://rmannibucau.wordpress.com> | Github
> > <https://github.com/rmannibucau> | LinkedIn
> > <https://www.linkedin.com/in/rmannibucau> | Book
> > <
> > https://www.packtpub.com/en-us/product/java-ee-8-high-performance-9781788473064
> > >
> > Javaccino founder (Java/.NET service - contact via linkedin)
> >
> >
> > Le jeu. 12 févr. 2026 à 17:24, Robert Stupp <sn...@snazy.de> a écrit :
> >
> > > 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 <di...@apache.org>
> > > 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.
> > > >
> > >
> >
Re: [DISCUSS] Removing server-side OpenAPI code generation
Posted by Yufei Gu <fl...@gmail.com>.
I don't have a strong opinion on either side. I think the hand-written or
ai-writtern gives us more controls and less duplicates, we may just go with
it.
Yufei
On Thu, Feb 12, 2026 at 8:53 AM Romain Manni-Bucau <rm...@gmail.com>
wrote:
> Hi
>
> +1 to be java first while it doesn't reach the runtime since it is totally
> useless to have these annotations, it must stay a build time generation and
> potentially the runtime can manipulate the openapi.json if needed (almost
> never but can be to filter by role).
>
> Romain Manni-Bucau
> @rmannibucau <https://x.com/rmannibucau> | .NET Blog
> <https://dotnetbirdie.github.io/> | Blog <https://rmannibucau.github.io/>
> | Old
> Blog <http://rmannibucau.wordpress.com> | Github
> <https://github.com/rmannibucau> | LinkedIn
> <https://www.linkedin.com/in/rmannibucau> | Book
> <
> https://www.packtpub.com/en-us/product/java-ee-8-high-performance-9781788473064
> >
> Javaccino founder (Java/.NET service - contact via linkedin)
>
>
> Le jeu. 12 févr. 2026 à 17:24, Robert Stupp <sn...@snazy.de> a écrit :
>
> > 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 <di...@apache.org>
> > 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.
> > >
> >
>
Re: [DISCUSS] Removing server-side OpenAPI code generation
Posted by Romain Manni-Bucau <rm...@gmail.com>.
Hi
+1 to be java first while it doesn't reach the runtime since it is totally
useless to have these annotations, it must stay a build time generation and
potentially the runtime can manipulate the openapi.json if needed (almost
never but can be to filter by role).
Romain Manni-Bucau
@rmannibucau <https://x.com/rmannibucau> | .NET Blog
<https://dotnetbirdie.github.io/> | Blog <https://rmannibucau.github.io/> | Old
Blog <http://rmannibucau.wordpress.com> | Github
<https://github.com/rmannibucau> | LinkedIn
<https://www.linkedin.com/in/rmannibucau> | Book
<https://www.packtpub.com/en-us/product/java-ee-8-high-performance-9781788473064>
Javaccino founder (Java/.NET service - contact via linkedin)
Le jeu. 12 févr. 2026 à 17:24, Robert Stupp <sn...@snazy.de> a écrit :
> 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 <di...@apache.org>
> 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.
> >
>
Re: [DISCUSS] Removing server-side OpenAPI code generation
Posted by Robert Stupp <sn...@snazy.de>.
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 <di...@apache.org>
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.
>