feat: Add opaque pagination

[madpah]

This PR (currently) adds Opaque Pagination to the /products endpoint as described in #179 - for review and comment before rolling it out to the other endpoints.

[madpah]

Pagination has been added to the following endpoints:

• /product/{uuid}/releases
• /productReleases
• /products
• /component/{uuid}/releases
• /components
• /componentReleases
• /componentRelease/{uuid}/collections
• /productRelease/{uuid}/collections

FYI @ppkarwasz @oej

[taleodor]

Hi @madpah , great work there.

I believe we should bring back all instances of id-type and id-value filters as those are not filters and not part of pagination. In relation to pagination, the server would need to take into account whether specific filtering was used. If that gets too complex, maybe we need a separate conversation on this.

Also we may need extra nesting due to behaviour of some generators, I'll try to test this over weekend based on your changes - essentially, at some point of TEA iterations, I was getting things like "inlinePaginationClass" without clear attribution to what class exactly was paginated. I'll get back on this but need a little extra time.

[madpah]

Hi @madpah , great work there.

I believe we should bring back all instances of id-type and id-value filters as those are not filters and not part of pagination. In relation to pagination, the server would need to take into account whether specific filtering was used. If that gets too complex, maybe we need a separate conversation on this.

Also we may need extra nesting due to behaviour of some generators, I'll try to test this over weekend based on your changes - essentially, at some point of TEA iterations, I was getting things like "inlinePaginationClass" without clear attribution to what class exactly was paginated. I'll get back on this but need a little extra time.

Understood - the purpose of those fields was not immediately clear - so I'll read add and aim to make it clear they are about result filtering and NOT pagination.

[madpah]

Hi @madpah , great work there.

I believe we should bring back all instances of id-type and id-value filters as those are not filters and not part of pagination. In relation to pagination, the server would need to take into account whether specific filtering was used. If that gets too complex, maybe we need a separate conversation on this.

Also we may need extra nesting due to behaviour of some generators, I'll try to test this over weekend based on your changes - essentially, at some point of TEA iterations, I was getting things like "inlinePaginationClass" without clear attribution to what class exactly was paginated. I'll get back on this but need a little extra time.

FWIW - the generated libs from this schema seem fine and work for me - if you see issues, let me know - might require a fix upstream in OpenAPI Generator 😉

[taleodor]

So the issue I mentioned is happening here, see below list of classes for Java server generator and notice TeaInlineObject ones:

-a----         3/15/2026   1:14 PM           8539 TeaArtifact.java
-a----         3/15/2026   1:14 PM           5807 TeaArtifactFormat.java
-a----         3/15/2026   1:14 PM           1629 TeaArtifactType.java
-a----         3/15/2026   1:14 PM           3141 TeaChecksum.java
-a----         3/15/2026   1:14 PM           1577 TeaChecksumType.java
-a----         3/15/2026   1:14 PM           4234 TeaCle.java
-a----         3/15/2026   1:14 PM           2842 TeaCleDefinitions.java
-a----         3/15/2026   1:14 PM          13734 TeaCleEvent.java
-a----         3/15/2026   1:14 PM           1611 TeaCleEventType.java
-a----         3/15/2026   1:14 PM           3992 TeaCleSupportDefinition.java
-a----         3/15/2026   1:14 PM           3209 TeaCleVersionSpecifier.java
-a----         3/15/2026   1:14 PM           7442 TeaCollection.java
-a----         3/15/2026   1:14 PM           1466 TeaCollectionBelongsToType.java
-a----         3/15/2026   1:14 PM           3275 TeaCollectionUpdateReason.java
-a----         3/15/2026   1:14 PM           1541 TeaCollectionUpdateReasonType.java
-a----         3/15/2026   1:14 PM           1995 TeaComplianceDocumentType.java
-a----         3/15/2026   1:14 PM           4241 TeaComponent.java
-a----         3/15/2026   1:14 PM           3556 TeaComponentRef.java
-a----         3/15/2026   1:14 PM           3878 TeaComponentReleaseWithCollection.java
-a----         3/15/2026   1:14 PM           3970 TeaDiscoveryInfo.java
-a----         3/15/2026   1:14 PM           2530 TeaErrorResponse.java
-a----         3/15/2026   1:14 PM           3137 TeaIdentifier.java
-a----         3/15/2026   1:14 PM           1387 TeaIdentifierType.java
-a----         3/15/2026   1:14 PM           4876 TeaInlineObject.java
-a----         3/15/2026   1:14 PM           4819 TeaInlineObject1.java
-a----         3/15/2026   1:14 PM           4784 TeaInlineObject2.java
-a----         3/15/2026   1:14 PM           4770 TeaInlineObject3.java
-a----         3/15/2026   1:14 PM           4791 TeaInlineObject4.java
-a----         3/15/2026   1:14 PM           3765 TeaPaginationDetails.java
-a----         3/15/2026   1:14 PM           4279 TeaProduct.java
-a----         3/15/2026   1:14 PM          10530 TeaProductRelease.java
-a----         3/15/2026   1:14 PM          10079 TeaRelease.java
-a----         3/15/2026   1:14 PM           7266 TeaReleaseDistribution.java
-a----         3/15/2026   1:14 PM           4745 TeaTeaServerInfo.java
-a----         3/15/2026   1:14 PM           1389 TeaUnknownErrorType.java

Steps to reproduce:

npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g spring -o tea-server/ --additional-properties="useSpringBoot3=true,modelNamePrefix=Tea"

Generally, AI should know how to fix this (it'll create some additional nested structures), but let me know if you need input from me.

[madpah]

What's the issue with the TeaInline* objects being generated @taleodor? This is fine in other languages for sure - so not sure of the issue here.

[taleodor]

What's the issue with the TeaInline* objects being generated @taleodor? This is fine in other languages for sure - so not sure of the issue here.

Basically, it makes it very hard to produce server code and then makes code unmaintainable because:

1. These are real classes we need to reference and they refer to specific objects and judging by name you have no idea what they are.
2. Numbers (TeaInlineObject1, 2, 3...) may change across updates and I'm not even sure if they are consistent across generation over the same schema file - making it nearly impossible to maintain properly.

[madpah]

Yeah - I see the inline objects - but don't understand what the issue is here @taleodor - is it because the naming is not deterministic, or something else?

[taleodor]

Yeah - I see the inline objects - but don't understand what the issue is here @taleodor - is it because the naming is not deterministic, or something else?

Yes, essentially we can't build proper server code like that. Like we need to use these classes to build pagination but we can't do it in a meaningful way - it's like working with obfuscated code.

[madpah]

Not sure I agree with the assessment @taleodor - I've used this before in both generated server and client code. The only real issue I've experienced is non-deterministic names of Classes which can be a pain.

Do you have a repo or commit somewhere that illustrates your pain that we can reference?

[taleodor]

I believe we shouldn't leave it like that in any case since it's public spec and this creates a lot of friction and uncertainty on the implementation side. I'll propose a fix to this PR - should have time over the weekend.