Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

SDK: Simplify OpenAPI Spec annotations

Aperta
  • Qualcosa non va?
#2,755 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
30/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
java, openapi
Ambito
api, backend

Direzione di ricerca

Start with the metrics records named in the issue, such as ProjectJobScheduleInputMetrics, and the @Schema annotations on their components. The proposal has two open implementation options (a Jandex AnnotationTransformation in timefold-solver-service-quarkus-deployment, or an OASFilter at runtime), so a maintainer has to choose one before any code is written. Done means a @Metric annotation that expands to the same OpenAPI output the quickstarts produce by hand today.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

process/needs triage

Is your feature request related to a problem? Please describe.
It's very frustrating to see how complex our OpenAPI Spec annotations have become to be platform compatible.

Every metric component on a ModelInputMetrics / ModelOutputMetrics record carries a large @Schema
annotation. Most of it repeats the same values on every field, and the example value is written twice.
This is one field from ProjectJobScheduleInputMetrics, which already has the inferred attributes
(type, name, @JsonFormat) removed:

@Schema(title = "Jobs", format = DataFormat.Values.NUMBER,
        description = "The number of jobs submitted in the input dataset.",
        examples = "24", minimum = "0", readOnly = true,
        extensions = { @Extension(name = X_TF_PRIORITY, value = "2"),
                @Extension(name = X_TF_EXAMPLE, value = "24") }) int jobs,

Only the following are specific to each metric:

  • title
  • description
  • the example value
  • format, when it isn't NUMBER

Everything else is either the same on every metric or can be derived:

Attribute Why it's boilerplate
readOnly = true Always true: metrics are only serialized, never deserialized.
minimum = "0" True for every count/total metric in the quickstarts so far.
x-tf-example Duplicates examples.
x-tf-priority Order in the Platform UI, this should honestly just have a default and be hidden
X_TF_PRIORITY / X_TF_EXAMPLE constants Redeclared as private constants in every metrics class.

Across the migrated quickstarts, this makes the metrics records hard to read, and it's easy to slip
(for example, an examples that no longer matches its x-tf-example).

Describe the solution you'd like

Add an SDK annotation, for example ai.timefold.solver.service.definition.api.metrics.Metric, that
carries only the metric-specific information:

public record ProjectJobScheduleInputMetrics(
        @Metric(title = "Allocations", example = "24",
                description = "The number of job allocations submitted in the input dataset.") int allocations,
        @Metric(title = "Jobs", example = "24",
                description = "The number of jobs submitted in the input dataset.") int jobs,
        @Metric(title = "Projects", example = "2",
                description = "The number of projects submitted in the input dataset.") int projects,
        @Metric(title = "Resources", example = "7",
                description = "The number of resources submitted in the input dataset.") int resources)
        implements
            ModelInputMetrics {
    ...
}

Sketch of the annotation:

@Target({ ElementType.FIELD, ElementType.RECORD_COMPONENT, ElementType.METHOD })
@Retention(RetentionPolicy.RUNTIME)
public @interface Metric {
    String title();
    String description();
    String example();
    String format() default DataFormat.Values.NUMBER;
    String minimum() default "0";      // "" to omit
    int priority() default -1;         // -1 = derive from declaration order
}

The SDK expands @Metric into the same OpenAPI output that the quickstarts produce by hand today:

  • title, description and format come straight from the annotation.
  • example and x-tf-example both come from example.
  • readOnly: true is always set.
  • minimum defaults to 0.
  • x-tf-priority comes from the component index (1-based) unless priority is set explicitly.
  • type is inferred from the Java type, as it is today.

Implementation options

  1. Build time, via a Jandex AnnotationTransformation in timefold-solver-service-quarkus-deployment.
    It rewrites @Metric into an equivalent @Schema (with @Extensions) on classes implementing
    ModelInputMetrics / ModelOutputMetrics. SmallRye OpenAPI then sees a normal @Schema, so nothing
    downstream changes. This option is preferred because the static spec is correct at build time too.
  2. Runtime, via an OASFilter that finds the metrics schemas and fills in the properties.
    It's simpler to write, but it relies on reflection to map schema properties back to record components.

Describe alternatives you've considered
Leaving it as is... for the user to deal with.

Lingua principale
Java
Stelle
1.8k
Fork
242
Merge medio
3g 2h
PR unite (30g)
51

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di TimefoldAI/timefold-solver

Tutte le issue di TimefoldAI/timefold-solver

Issue simili

Altre issue su Java

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.