REST API

// TimetableDto.java
public class TimetableDto implements ModelInput, ModelOutput {

    @Schema(required = true, description = "The unique identifier of timetable")
    private String name;
    @Schema(required = true, description = "List of timeslots")
    private List<Timeslot> timeslots;
    @Schema(required = true, description = "List of lessons")
    private List<Lesson> lessons;

    // Getters, Setters and constructor excluded.
}

// TimetableSchedulingResource.java
@Tag(name = "School Timetabling",
        description = "School timetabling service assigning lessons to timeslots.") // OpenAPI documentation annotation
@Path("/v1/timetables") //sets the root path
public interface TimetableSchedulingResource extends ModelRest {
}

@ApplicationScoped
public class TimetableConvertor implements ModelConvertor<HardSoftLongScore, TimetableDto, Timetable, EmptyModelConfigOverrides, EmptyModelInputMetrics, EmptyModelOutputMetrics, Timetable> {

    @Override
    public Timetable toSolverModel(TimetableDto modelInput, TimetableDto previousModelOutput, ModelConfig<EmptyModelConfigOverrides> modelConfig) {
        return // Mapping logic
    }

    @Override
    public Timetable toSolverModel(TimetableDto modelInput, ModelConfig<EmptyModelConfigOverrides> modelConfig) {
        return // Mapping logic
    }

    @Override
    public TimetableDto toModelOutput(Timetable solverModel) {
        return // Mapping logic
    }
}

@ApplicationScoped
public class TimetableValidator implements ModelValidator<TimetableDto, TimetableConfigOverrides> {

    @Override
    public void validate(ValidationBuilder validationBuilder, TimetableDto input, ModelConfig<TimetableConfigOverrides> modelConfig) {

        //validation logic here, simplified example here.
        if(hasDuplicateTeacherNames(input)) {
            validationBuilder.addIssue(TimetableValidationIssue.DUPLICATE_TEACHER.asIssueType(), new DuplicateTeacherDetail("Ann"));
        }
    }
}

public enum TimetableValidationIssue {

    DUPLICATE_TEACHER(IssueCode.of("DUPLICATE_TEACHER"), IssueSeverity.ERROR,
            "Duplicate teacher names found.");

    private final IssueType issueType;

    TimetableValidationIssue(IssueCode code, IssueSeverity severity, String message) {
        this.issueType = new IssueType(code, severity, message);
    }

    public IssueType asIssueType() {
        return issueType;
    }

    public record DuplicateTeacherDetail(String teacherName) implements IssueDetail {
    }
}

@Tag(name = "School Timetabling",
        description = "School timetabling service assigning lessons to timeslots.") //OpenAPI documentation annotation
@Path("/v1/timetables") //sets the root path
public interface TimetableSchedulingResource extends ModelRest {

    @APIResponses(value = {
        @APIResponse(responseCode = "500", description = "In case of processing errors",
                content = @Content(mediaType = MediaType.APPLICATION_JSON,
                        schema = @Schema(implementation = ErrorInfo.class))),
        @APIResponse(responseCode = "200", description = "List of all teachers in all optimization runs.",
                content = @Content(mediaType = MediaType.APPLICATION_JSON,
                        schema = @Schema(implementation = ListTeachersResponseDto.class))) })
    @Operation(operationId = "list-teachers-in-solver-model",
            summary = "Lists all teachers in the solver model.")
    @GET
    @Path("/insights/teachers")
    @Produces(MediaType.APPLICATION_JSON)
    default Response insightsTeachers() {
        var teachers = //get the list of teachers
        return Response.ok(teachers).build();
    }
}