feat(api)!: geef aanleveren een eigen resource zodat de generator-update kan landen

[ericwout-overheid]

Wat er verandert

De code-generator-update naar 7.24.0 maakte drie van de zes magazijn-operaties onbereikbaar.
Deze PR neemt de update alsnog, door de oorzaak weg te nemen in plaats van de update tegen te
houden.

De oorzaak. Upstream "Fix path shadowing"
laat het class-basispad van een tag vervallen zodra dat pad de routes van een ándere tag zou
afvangen; de operaties dragen hun volledige pad dan op methodeniveau. Dat is geldige JAX-RS, maar
Quarkus REST resolvet eerst op class-basispad en beantwoordt zo'n operatie met 405. In het magazijn
deelden Aanlever, Ophaal en Beheer allemaal /berichten:

interface	class-@Path	gevolg
OphaalApi	"/berichten"	wint de subtree
AanleverApi	""	POST /berichten → 405
BeheerApi	""	PATCH/DELETE /berichten/{berichtId} → 405

De oplossing. Elke tag bezit nu zijn eigen pad-subtree:

operatie	was	is	tag
aanleveren	POST /berichten	POST /aanleveringen	Aanlever
lijst, detail, bijlage	/berichten…	ongewijzigd	Ophaal → Berichten
status, verwijderen	/berichten/{berichtId}	ongewijzigd	Beheer → Berichten

Gegenereerd wordt nu AanleverApi @Path("/aanleveringen") naast BerichtenApi @Path("/berichten") —
twee disjuncte subtrees, geen lege class-@Path meer.

Ophaal en Beheer moesten één tag worden omdat GET en PATCH/DELETE op
/berichten/{berichtId} hetzelfde pad delen; geen ADR-conforme hernoeming scheidt die. Alleen de
HTTP-laag komt daardoor samen in BerichtenResource — BerichtOphaalService en
BerichtBeheerService blijven gescheiden, net als hun tests.

Aanleveren houdt wél een eigen resource. Het is de afzender-kant die via de FSC-inway naar binnen
schrijft, tegenover de ontvanger-kant met X-Ontvanger en BerichtAutorisatie.vereisOntvanger(...).
Die twee autorisatieregimes in één class zetten zou de verkeerde besparing zijn.

Waarom niet wachten

De bijbehorende Quarkus-issue (quarkusio/quarkus#26496)
is gesloten en gerepareerd in 3.24.0.CR1, ruim vóór onze 3.38.1. Die fix dekt @Path("/base")
tegenover @Path("/base/{id}"), niet @Path("") tegenover @Path("/berichten") — gemeten: de 405's
treden op onze huidige Quarkus-versie nog steeds op. De generator doet niets fouts, dus wachten
lost hier niets op.

Wel opgevallen en apart te melden bij OpenAPITools: de shadow-detectie is asymmetrisch.
Ophaal's commonPath /berichten was exact gelijk aan Aanlever's pad, dus had ook Ophaal zijn
class-@Path moeten verliezen. Dan hadden alle drie de interfaces @Path("") gehad en had de
routering gewoon gewerkt.

Meegenomen fout

BerichtDtoMapperTest faalde op deze branch, los van de bump. De HAL-links laten
.path(ApiInfo.BASE_PATH) weg sinds de prefix één keer via quarkus.rest.path gezet wordt, maar de
test-fixture bouwde zijn base-URI nog zonder die prefix. De fixture spiegelt nu de runtime-waarde.

Wat er meeverhuist

Alleen het schrijfpad. MagazijnAanleverClient in de demo-console (class-@Path naar /api/v1,
paden per methode, want POST en PATCH zitten nu op verschillende roots), de Bruno-map
berichten/ → aanleveren/, demo/smoke.sh, apis.json en 34 POST-call-sites in tests. De
lees-clients — MagazijnClient in de sessiecache-library én in de uitvraag — raken /berichten en
blijven ongemoeid, net als de WireMock-mappings (die stubben leespaden).

Verificatie

• ./mvnw clean verify — alle modules groen: fbs-common 296, magazijnregister 30, sessiecache 295,
  magazijn 379, uitvraag 194, demo-console 43
• RouteDekkingTest uit test(api): bewaak dat elk pad uit de spec ook echt bij een resource aankomt #192 tijdelijk meegedraaid op deze branch: 12/12 groen, waar dezelfde
  test vóór deze wijziging drie 405's meldde
• detekt: geen bevindingen; geen nieuwe build-warnings

Vervangt #147

Deze wijziging zat eerst op de dependabot-branch van #147. De deploy-workflow slaat bouwen en
preview-deployen bewust over voor bot-PR's, waardoor de drie deploy-preview-*-checks daar op
skipped bleven staan — bij een brekende contractwijziging is dat precies de verificatie die je
niet wilt missen. Dezelfde commits staan hier op een eigen branch, zodat de volledige CI draait.
De bump naar 7.24.0 reist mee; #147 kan dicht.

Gestapeld op #192

Deze PR staat op de branch van #192 en moet er dus ná mergen. Dat is geen volgorde-afspraak maar
een echte afhankelijkheid: #192 legt in RouteDekkingTest vast dat de magazijn-spec drie paden
telt, en deze PR maakt er vier van. Los gemerged zou de bewaker op main omvallen. Gestapeld
draait die test hier meteen tegen de nieuwe spec — 12/12 groen, waar dezelfde test vóór deze
wijziging drie 405's meldde.

De diff hierboven toont alleen het eigen werk; GitHub zet de base op main zodra #192 gemerged is.

Closes MinBZK/MijnOverheidZakelijk#870

🤖 Generated with Claude Code

[ericwout-overheid]

Upstream melden? Besluit gevraagd

Bij het uitzoeken van deze wijziging bleek de shadow-detectie in de generator niet te doen wat hij belooft. Dat raakt ons niet meer — deze PR neemt de oorzaak weg — maar het is wel iets waar andere gebruikers tegenaan lopen. Vandaar de vraag of we het melden, en waar.

Wat er aan de hand is

De guard uit OpenAPITools/openapi-generator#23871 slaat aan zodra het gemeenschappelijke pad van een tag de routes van een ándere tag zou afvangen. Maar hij slaat juist níét aan wanneer twee tags exact hetzelfde pad delen — en dat is de zwaarste vorm van overlap. In wouldShadowOtherTags:

for (String path : allResourcePaths) {
    if (currentTagPaths.contains(path)) {
        continue;
    }
    if (path.startsWith(commonPath + "/") || path.equals(commonPath)) {
        return true;
    }
}

allResourcePaths is een Set<String>, dus een pad dat twee tags declareren staat er één keer in en zit voor allebei óók in currentTagPaths. Beide tags slaan daardoor precies het pad over dat met de ander botst. Eén tag houdt het basispad, de andere krijgt @Path("") — en op Quarkus REST is die tweede daarna onbereikbaar.

Wat ik heb nagetrokken

• Broncode van AbstractJavaJAXRSServerCodegen op master gelezen, niet de PR-beschrijving.
• Minimale repro gebouwd (twee tags, drie operaties) en echt gegenereerd met 7.24.0: AlphaApi krijgt @Path(""), BetaApi houdt @Path("/items").
• Dezelfde repro onder 7.23.0 gedraaid: daar krijgen béíde interfaces @Path("/items"). Het is dus een regressie, gemeten en niet aangenomen.

Waarom dit een melding is en geen PR

De voor de hand liggende fix — die continue weghalen — laat álle botsende tags hun prefix verliezen, dus dan krijgen ze allemaal @Path(""). Of Quarkus REST daar wél goed mee omgaat heb ik niet getest. Ik wil upstream geen oplossing aandragen die ik niet heb geverifieerd.

Te kiezen

1. Nieuw issue op OpenAPITools/openapi-generator — beste vindbaarheid voor anderen die hetzelfde treffen.
2. Comment onder #23871 — de auteur van de fix leest daar mee, drempel lager, maar het verdwijnt sneller uit beeld.
3. Niet melden — het kost ons niets meer en we hebben geen upstream-fix nodig.

Mijn voorkeur is 1. De tekst ligt klaar; hieronder, zodat wie hem plaatst niets hoeft te herschrijven.

Concept-issue (Engels)

Title: [BUG][jaxrs-spec] Path shadowing check skips paths shared by two tags, leaving one tag with an empty class-level @Path``

Description

The shadowing guard added in #23871 (for #23414) does not fire when two tags declare operations on the same path. In that case one tag keeps the common prefix as its class-level @Path and the other tag is emitted with @Path("") plus full paths on its methods — which is the situation the guard was introduced to prevent.

The cause is the skip in wouldShadowOtherTags (AbstractJavaJAXRSServerCodegen):

for (String path : allResourcePaths) {
    if (currentTagPaths.contains(path)) {
        continue;
    }
    if (path.startsWith(commonPath + "/") || path.equals(commonPath)) {
        return true;
    }
}

allResourcePaths is a Set<String>, so a path declared by two tags appears once and is a member of currentTagPaths for both of them. Each tag therefore skips exactly the path that collides with the other tag, and the strongest form of overlap — an identical path — is invisible to the check.

Reproduction

shadow-repro.yaml:

openapi: 3.0.3
info:
  title: Shadow repro
  version: 1.0.0
tags:
  - name: Alpha
  - name: Beta
paths:
  /items:
    post:
      tags: [Alpha]
      operationId: createItem
      responses:
        '201':
          description: created
    get:
      tags: [Beta]
      operationId: listItems
      responses:
        '200':
          description: ok
  /items/{itemId}:
    get:
      tags: [Beta]
      operationId: getItem
      parameters:
        - name: itemId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ok

Generated with openapi-generator-maven-plugin 7.24.0, generatorName: jaxrs-spec, interfaceOnly=true, useTags=true, useJakartaEe=true:

// BetaApi.java
@Path("/items")
public interface BetaApi {
    @GET                          void listItems();
    @GET @Path("/{itemId}")       void getItem(@PathParam("itemId") String itemId);
}

// AlphaApi.java
@Path("")
public interface AlphaApi {
    @POST @Path("/items")         void createItem();
}

Walking through the check: Alpha owns {/items}, so its external set is {/items/{itemId}}, which starts with /items/ → shadowing detected → @Path(""). Beta owns {/items, /items/{itemId}}, so every entry in allResourcePaths is skipped by currentTagPaths.contains(path) → no shadowing detected → it keeps @Path("/items").

Impact

The result depends on how the runtime matches requests. On Quarkus REST (RESTEasy Reactive) 3.38.1 resolution happens on the class-level base path first: POST /items lands in the /items node owned by BetaApi, finds no POST there, and returns 405 — the class with @Path("") is never consulted. A closely related overlap (@Path("/base") vs @Path("/base/{id}")) was reported as quarkusio/quarkus#26496 and fixed in 3.24.0.CR1; this variant, where one class has an empty base path, still ends in 405.

Concretely, in our API three of six operations became unreachable after upgrading from 7.23.0 to 7.24.0: a POST and a PATCH/DELETE pair that shared /berichten and /berichten/{id} with a read-only tag.

Notes

We have resolved this on our side by giving every tag a disjoint path subtree, so we are not blocked. We are reporting it because the guard silently does not fire in a case it appears intended to cover, and the failure mode is a route that disappears without any build-time signal.

One caveat on the obvious fix: simply removing the continue would make every colliding tag lose its prefix, so all of them would be emitted with @Path(""). That is the shape the guard already produces for the shadowed tags today, and we have not verified that a set of resource classes all sharing an empty base path resolves correctly on Quarkus REST. So the symmetric variant may not be an improvement in practice — hence a report rather than a PR.

Question for maintainers: are two tags sharing an identical path meant to be supported by the jaxrs-spec generator? If it is, the shadowing check likely needs to account for it; if it is not, a generation-time warning would make the constraint visible instead of surfacing as a 405 at runtime.

openapi-generator version

7.24.0 (regression relative to 7.23.0, which emitted a class-level @Path per tag and routed correctly).

[github-actions]

JaCoCo coverage

Overall Project	91.64%	🍏
Files changed	100%	🍏

Module	Coverage
FBS Berichtenmagazijn Service	92.8%	🍏
FBS Berichten Uitvraag Service	84.06%	🍏

Files

Module	File	Coverage
FBS Berichtenmagazijn Service	BijlageContentTypeFilter.kt	100%	🍏
	AanleverResource.kt	99.44%	🍏
	BerichtDtoMapper.kt	98.74%	🍏
	BerichtenResource.kt	98.21%	🍏
FBS Berichten Uitvraag Service	UitvraagResource.kt	100%	🍏
	AanmeldResource.kt	100%	🍏
	OphalenSseResource.kt	95.35%	🍏

[github-actions]

Fuzz-basis-image loopt achter op de dependency-declaraties

De dependency-declaraties zijn gewijzigd, dus het fuzz-basis-image met de warme
Maven-repository hoort opnieuw gebouwd te worden.

Blokkeert niets. De fuzz-controle werkt gewoon; hij haalt alleen het verschil
elke run opnieuw op, en is daarmee zo traag als vóór het basis-image.

Na de merge naar main bouwt de workflow Fuzz-basis-image het nieuwe image en
print hij de digest. Zet die in .clusterfuzzlite/Dockerfile en deze melding verdwijnt.