refactor(openapi): stop redirecting inline enum schemas onto domain enums

Now that model.mustache renders a real enumOuterClass for a top-level enum
schema (previous commit), the generator can synthesize its own DTO-side enum
per module instead of being pointed at the hand-written domain enum via
schemaMappings. Removed the enum-only mapping entries for Gender,
DeactivationReason, DrivingLicenseGroup, TrainerLevel, RefereeLevel (members)
and EventStatus (events), and added explicit DTO<->domain conversions at the
REST boundary (MemberMapper, UpdateMemberRequestMapper, MemberController,
EventController) so the domain enums stay untouched and fully decoupled from
the wire representation.

Authority stays mapped: it's used pervasively outside the DTO layer
(@HasAuthority annotations, security interceptors, JWT claims, OAuth2 scopes),
so redirecting it would force Authority/DTO conversions into core security
code for no benefit.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: dapolach

backend/build.gradle.kts

@@ -430,17 +430,24 @@ openApiModule(
         "RegisterMemberRequest",
         "AddressRequest",
         "SuspendMembershipRequest",
-        "UpdateMemberRequest"
+        "UpdateMemberRequest",
+        // Enum schemas — must be listed explicitly so the generator emits them; without a
+        // schemaMapping redirecting them onto the domain enum, they need `models` to know to
+        // generate the type at all (see the mapping comment below for why they're no longer mapped).
+        "Gender",
+        "UpdateMemberRequest_gender",
+        "DeactivationReason",
+        "DrivingLicenseGroup",
+        "TrainerLicenseDto_level",
+        "RefereeLicenseDto_level"
     ),
     mappings = mapOf(
-        "Gender" to "com.klabis.members.domain.Gender",
-        // UpdateMemberRequest.gender inlines the enum rather than $ref-ing Gender, so that it keeps
-        // both its JsonNullable wrapper and x-klabis-authority. See the comment in members.yaml.
-        "UpdateMemberRequest_gender" to "com.klabis.members.domain.Gender",
-        "DeactivationReason" to "com.klabis.members.domain.DeactivationReason",
-        "DrivingLicenseGroup" to "com.klabis.members.domain.DrivingLicenseGroup",
-        "TrainerLicenseDto_level" to "com.klabis.members.domain.TrainerLevel",
-        "RefereeLicenseDto_level" to "com.klabis.members.domain.RefereeLevel",
+        // Gender/DeactivationReason/DrivingLicenseGroup/TrainerLicenseDto_level/RefereeLicenseDto_level
+        // used to be redirected here onto the hand-written domain enums (Gender, DeactivationReason,
+        // DrivingLicenseGroup, TrainerLevel, RefereeLevel). Now that model.mustache renders a real
+        // enumOuterClass for a promoted/$ref'd top-level enum, the generator synthesizes its own DTO
+        // enum for each of these instead — see MemberMapper/UpdateMemberRequestMapper for the explicit
+        // conversion between the generated DTO enum and the domain enum at the REST boundary.
         // getMember's application/json response references MemberDetailsResponse directly (see
         // members.yaml) — no envelope redirection needed since the schema name already matches the
         // Java type. listMembers still needs one: its application/json response is a bare array
@@ -536,10 +543,16 @@ openApiModule(
         "UpdateEventRankingRequest",
         "EntryFeeRequest",
         "CreateEventRequest",
-        "CreateEventCategoryRequest"
+        "CreateEventCategoryRequest",
+        // Enum schema — must be listed explicitly so the generator emits it (see the mapping comment
+        // below for why it's no longer redirected onto the domain enum).
+        "EventStatus"
     ),
     mappings = mapOf(
-        "EventStatus" to "com.klabis.events.domain.EventStatus",
+        // EventStatus used to be redirected here onto the hand-written domain enum
+        // com.klabis.events.domain.EventStatus. Now that model.mustache renders a real enumOuterClass
+        // for a top-level enum schema, the generator synthesizes its own DTO enum instead — see
+        // EventDto/EventSummaryDto/EventController for the explicit conversion to/from the domain enum.
         // listEvents is genuinely paginated (x-spring-paginated: true) — no array shape carries
         // pagination metadata, so both the envelope and the named array sibling stay mapped onto
         // Page<T> (finance module precedent: removing either one degrades the generated return type

backend/src/main/java/com/klabis/events/infrastructure/restapi/EventController.java

@@ -19,7 +19,6 @@
 import com.klabis.events.domain.Event;
 import com.klabis.events.domain.EventFilter;
 import com.klabis.events.domain.EventRegistration;
-import com.klabis.events.domain.EventStatus;
 import com.klabis.members.*;
 import com.klabis.members.infrastructure.restapi.MembersApi;
 import jakarta.annotation.Nullable;
@@ -189,7 +188,7 @@ private EventFilter buildFilter(
             List<UUID> eventTypeId,
             CurrentUserData currentUser) {
 
-        EventFilter filter = status != null ? EventFilter.byStatus(status) : EventFilter.none();
+        EventFilter filter = status != null ? EventFilter.byStatus(toDomainStatus(status)) : EventFilter.none();
 
         if (q != null) {
             filter = filter.withFulltext(q);
@@ -243,6 +242,10 @@ private EventFilter buildFilter(
         return filter;
     }
 
+    private static com.klabis.events.domain.EventStatus toDomainStatus(EventStatus status) {
+        return status == null ? null : com.klabis.events.domain.EventStatus.valueOf(status.name());
+    }
+
     private void validateSortFields(Sort sort) {
         final var allowedSortFields = Set.of(
                 "id",
@@ -418,7 +421,7 @@ static MemberId resolveMemberId(Authentication auth) {
     }
 
     static boolean shouldOfferRegistration(Event event) {
-        return event.getStatus() == EventStatus.ACTIVE && event.areRegistrationsOpen();
+        return event.getStatus() == com.klabis.events.domain.EventStatus.ACTIVE && event.areRegistrationsOpen();
     }
 
     static boolean isCoordinatorOrHasManageAuthority(Authentication auth, Event event) {
@@ -492,7 +495,7 @@ public void process(EntityModel<EventDto> dtoModel, Event event) {
         klabisLinkTo(methodOn(EventsApi.class).listEvents(null, null, null, null, null, null, null, null, null, null, null, null))
                 .ifPresent(link -> dtoModel.add(link.withRel("collection")));
 
-        if (event.getStatus() != EventStatus.DRAFT) {
+        if (event.getStatus() != com.klabis.events.domain.EventStatus.DRAFT) {
             klabisLinkTo(methodOn(EventRegistrationsApi.class).listRegistrations(eventId, null))
                     .ifPresent(link -> dtoModel.add(link.withRel("registrations").expand()));
         }

backend/src/main/java/com/klabis/members/infrastructure/restapi/MemberController.java

@@ -97,7 +97,7 @@ public ResponseEntity<Void> suspendMember(
 
         var command = new Member.SuspendMembership(
                 currentUserId,
-                request.reason(),
+                memberMapper.deactivationReasonToDomain(request.reason()),
                 request.note()
         );
 

backend/src/main/java/com/klabis/members/infrastructure/restapi/MemberMapper.java

@@ -30,10 +30,23 @@ interface MemberMapper {
     @Mapping(target = "birthNumber", expression = "java(member.getBirthNumber() != null ? member.getBirthNumber().value() : null)")
     @Mapping(target = "bankAccountNumber", expression = "java(member.getBankAccountNumber() != null ? member.getBankAccountNumber().value() : null)")
     @Mapping(target = "suspendedBy", expression = "java(member.getSuspendedBy() != null ? member.getSuspendedBy().uuid().toString() : null)")
+    @Mapping(target = "gender", source = "gender")
+    @Mapping(target = "drivingLicenseGroup", source = "drivingLicenseGroup")
+    @Mapping(target = "suspensionReason", source = "suspensionReason")
     MemberDetailsResponse toDetailsResponse(Member member);
 
     AddressResponse addressToResponse(Address address);
 
+    Gender genderToDto(com.klabis.members.domain.Gender gender);
+
+    com.klabis.members.domain.Gender genderToDomain(Gender gender);
+
+    DrivingLicenseGroup drivingLicenseGroupToDto(com.klabis.members.domain.DrivingLicenseGroup drivingLicenseGroup);
+
+    DeactivationReason deactivationReasonToDto(com.klabis.members.domain.DeactivationReason reason);
+
+    com.klabis.members.domain.DeactivationReason deactivationReasonToDomain(DeactivationReason reason);
+
     default GuardianDTO guardianToResponse(GuardianInformation guardian) {
         if (guardian == null) {
             return null;
@@ -56,11 +69,15 @@ default GuardianDTO guardianToResponse(GuardianInformation guardian) {
 
     RefereeLicenseDto refereeLicenseToDto(RefereeLicense refereeLicense);
 
+    TrainerLicenseDtoLevel trainerLevelToDto(com.klabis.members.domain.TrainerLevel level);
+
+    RefereeLicenseDtoLevel refereeLevelToDto(com.klabis.members.domain.RefereeLevel level);
+
     default RegistrationPort.RegisterNewMember toRegisterNewMemberCommand(
             RegisterMemberRequest request, UserId registeredBy) {
         return new RegistrationPort.RegisterNewMember(
                 createPersonalInformation(request.firstName(), request.lastName(),
-                        request.dateOfBirth(), request.gender(), request.nationality()),
+                        request.dateOfBirth(), genderToDomain(request.gender()), request.nationality()),
                 request.address() != null ? new Address(request.address().street(), request.address().city(),
                         request.address().postalCode(), request.address().country()) : null,
                 EmailAddress.of(request.email()),
@@ -78,7 +95,7 @@ default PersonalInformation createPersonalInformation(
             String firstName,
             String lastName,
             LocalDate dateOfBirth,
-            Gender gender,
+            com.klabis.members.domain.Gender gender,
             String nationality
     ) {
         return PersonalInformation.of(firstName, lastName, dateOfBirth, nationality, gender);

backend/src/main/java/com/klabis/members/infrastructure/restapi/UpdateMemberRequestMapper.java

@@ -22,16 +22,16 @@ static Member.UpdateMember toCommand(UpdateMemberRequest request, UserId updated
                     unwrap(request.nationality()),
                     map(request.bankAccountNumber(), UpdateMemberRequestMapper::toBankAccountNumber),
                     map(request.identityCard(), dto -> IdentityCard.of(dto.cardNumber(), dto.validityDate())),
-                    request.drivingLicenseGroup(),
+                    map(request.drivingLicenseGroup(), UpdateMemberRequestMapper::toDrivingLicenseGroup),
                     map(request.medicalCourse(), UpdateMemberRequestMapper::toMedicalCourse),
-                    map(request.trainerLicense(), dto -> TrainerLicense.of(dto.level(), dto.validityDate())),
-                    map(request.refereeLicense(), dto -> RefereeLicense.of(dto.level(), dto.validityDate())),
+                    map(request.trainerLicense(), dto -> TrainerLicense.of(toTrainerLevel(dto.level()), dto.validityDate())),
+                    map(request.refereeLicense(), dto -> RefereeLicense.of(toRefereeLevel(dto.level()), dto.validityDate())),
                     request.dietaryRestrictions(),
                     map(request.guardian(), UpdateMemberRequestMapper::toGuardianInformation),
                     unwrap(request.firstName()),
                     unwrap(request.lastName()),
                     unwrap(request.dateOfBirth()),
-                    unwrap(request.gender()),
+                    toGender(unwrap(request.gender())),
                     map(request.birthNumber(), UpdateMemberRequestMapper::toBirthNumber),
                     updatedBy
             );
@@ -74,6 +74,22 @@ private static BirthNumber toBirthNumber(String value) {
         return value.isBlank() ? null : BirthNumber.of(value);
     }
 
+    private static com.klabis.members.domain.DrivingLicenseGroup toDrivingLicenseGroup(DrivingLicenseGroup dto) {
+        return dto == null ? null : com.klabis.members.domain.DrivingLicenseGroup.valueOf(dto.name());
+    }
+
+    private static com.klabis.members.domain.Gender toGender(UpdateMemberRequestGender dto) {
+        return dto == null ? null : com.klabis.members.domain.Gender.valueOf(dto.name());
+    }
+
+    private static com.klabis.members.domain.TrainerLevel toTrainerLevel(TrainerLicenseDtoLevel dto) {
+        return dto == null ? null : com.klabis.members.domain.TrainerLevel.valueOf(dto.name());
+    }
+
+    private static com.klabis.members.domain.RefereeLevel toRefereeLevel(RefereeLicenseDtoLevel dto) {
+        return dto == null ? null : com.klabis.members.domain.RefereeLevel.valueOf(dto.name());
+    }
+
     private static GuardianInformation toGuardianInformation(GuardianDTO dto) {
         return new GuardianInformation(
                 dto.firstName(),

backend/src/test/java/com/klabis/events/infrastructure/restapi/EventControllerTest.java

@@ -15,6 +15,7 @@
 import com.klabis.events.application.MemberRegistrationSanctionPort;
 
 import com.klabis.events.domain.*;
+import com.klabis.events.domain.EventStatus;
 import com.klabis.members.MemberAccommodationDto;
 import com.klabis.members.MemberDto;
 import com.klabis.members.MemberId;

backend/src/test/java/com/klabis/members/infrastructure/restapi/MemberControllerApiTest.java

@@ -9,6 +9,8 @@
 import com.klabis.members.*;
 import com.klabis.members.application.*;
 import com.klabis.members.domain.*;
+import com.klabis.members.domain.Gender;
+import com.klabis.members.domain.DeactivationReason;
 import com.klabis.groups.common.domain.FamilyGroupFilter;
 import com.klabis.groups.common.domain.TrainingGroupFilter;
 import org.junit.jupiter.api.Disabled;

backend/src/test/java/com/klabis/members/infrastructure/restapi/MemberMappingTests.java

@@ -139,7 +139,7 @@ void shouldMapValidTrainerLicenseCorrectly() {
             TrainerLicenseDto dto = testedSubject.trainerLicenseToDto(license);
 
             assertThat(dto).isNotNull();
-            assertThat(dto.level()).isEqualTo(TrainerLevel.T1);
+            assertThat(dto.level()).isEqualTo(TrainerLicenseDtoLevel.T1);
             assertThat(dto.validityDate()).isEqualTo(LocalDate.of(2026, 12, 31));
         }
 
@@ -157,7 +157,7 @@ void shouldMapTrainerLicenseWithTodayValidityDate() {
             TrainerLicense license = new TrainerLicense(TrainerLevel.T3, today);
             TrainerLicenseDto dto = testedSubject.trainerLicenseToDto(license);
 
-            assertThat(dto.level()).isEqualTo(TrainerLevel.T3);
+            assertThat(dto.level()).isEqualTo(TrainerLicenseDtoLevel.T3);
             assertThat(dto.validityDate()).isEqualTo(today);
         }
     }
@@ -173,7 +173,7 @@ void shouldMapValidRefereeLicenseCorrectly() {
             RefereeLicenseDto dto = testedSubject.refereeLicenseToDto(license);
 
             assertThat(dto).isNotNull();
-            assertThat(dto.level()).isEqualTo(RefereeLevel.R2);
+            assertThat(dto.level()).isEqualTo(RefereeLicenseDtoLevel.R2);
             assertThat(dto.validityDate()).isEqualTo(LocalDate.of(2026, 12, 31));
         }
 
@@ -253,7 +253,7 @@ void shouldMapMemberWithAllFieldsToDetailsResponse() {
                     .withMedicalCourse(medicalCourse)
                     .withTrainerLicense(trainerLicense)
                     .withChipNumber("CHIP123")
-                    .withDrivingLicenseGroup(DrivingLicenseGroup.B)
+                    .withDrivingLicenseGroup(com.klabis.members.domain.DrivingLicenseGroup.B)
                     .withDietaryRestrictions("No restrictions")
                     .build();
 
@@ -274,8 +274,9 @@ void shouldMapMemberWithAllFieldsToDetailsResponse() {
             assertThat(dto.medicalCourse()).isNotNull();
             assertThat(dto.medicalCourse().completionDate()).isEqualTo(LocalDate.of(2024, 1, 1));
             assertThat(dto.trainerLicense()).isNotNull();
-            assertThat(dto.trainerLicense().level()).isEqualTo(TrainerLevel.T2);
-            assertThat(dto.drivingLicenseGroup()).isEqualTo(DrivingLicenseGroup.B);
+            assertThat(dto.trainerLicense().level()).isEqualTo(TrainerLicenseDtoLevel.T2);
+            assertThat(dto.drivingLicenseGroup()).isEqualTo(
+                    com.klabis.members.infrastructure.restapi.DrivingLicenseGroup.B);
             assertThat(dto.dietaryRestrictions()).isEqualTo("No restrictions");
         }
 
@@ -350,7 +351,7 @@ void shouldMapMemberWithOnlyTrainerLicense() {
             assertThat(dto.identityCard()).isNull();
             assertThat(dto.medicalCourse()).isNull();
             assertThat(dto.trainerLicense()).isNotNull();
-            assertThat(dto.trainerLicense().level()).isEqualTo(TrainerLevel.T1);
+            assertThat(dto.trainerLicense().level()).isEqualTo(TrainerLicenseDtoLevel.T1);
         }
 
         @Test

backend/src/test/java/com/klabis/members/infrastructure/restapi/UpdateMemberApiTest.java

@@ -10,6 +10,8 @@
 import com.klabis.members.application.ManagementPort;
 import com.klabis.members.application.MemberNotFoundException;
 import com.klabis.members.domain.*;
+import com.klabis.members.domain.Gender;
+import com.klabis.members.domain.DrivingLicenseGroup;
 import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.Nested;
 import org.junit.jupiter.api.Test;