Skip to content

Commit e03b0fd

Browse files
bhufmannbhufmann
committed
swagger: Add missing required flags for multiple data structures
It also updates descriptions of optional fields if needed to better clarify it. Align serializers for optional fields where applicable. fixes eclipse-cdt-cloud/trace-server-protocol#125 Signed-off-by: Bernd Hufmann <[email protected]>
1 parent 79180e4 commit e03b0fd

28 files changed

+140
-91
lines changed

‎trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core/src/org/eclipse/tracecompass/incubator/internal/trace/server/jersey/rest/core/model/AnnotationCategoriesModel.java‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/**********************************************************************
2-
* Copyright (c) 2021 Ericsson
2+
* Copyright (c) 2021, 2025 Ericsson
33
*
44
* All rights reserved. This program and the accompanying materials are
55
* made available under the terms of the Eclipse Public License 2.0 which
@@ -15,6 +15,7 @@
1515

1616
import io.swagger.v3.oas.annotations.media.ArraySchema;
1717
import io.swagger.v3.oas.annotations.media.Schema;
18+
import io.swagger.v3.oas.annotations.media.Schema.RequiredMode;
1819

1920
/**
2021
* Contributes to the model used for TSP swagger-core annotations.
@@ -25,6 +26,6 @@ public interface AnnotationCategoriesModel {
2526
/**
2627
* @return The annotation categories.
2728
*/
28-
@ArraySchema(arraySchema = @Schema(description = "Array of all the categories"))
29+
@ArraySchema(arraySchema = @Schema(description = "Array of all the categories"), schema = @Schema(requiredMode = RequiredMode.REQUIRED))
2930
List<String> getAnnotationCategories();
3031
}

‎trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core/src/org/eclipse/tracecompass/incubator/internal/trace/server/jersey/rest/core/model/Bookmark.java‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*******************************************************************************
2-
* Copyright (c) 2024 Ericsson
2+
* Copyright (c) 2024, 2025 Ericsson
33
*
44
* All rights reserved. This program and the accompanying materials are
55
* made available under the terms of the Eclipse Public License 2.0 which
@@ -18,6 +18,7 @@
1818
import com.fasterxml.jackson.annotation.JsonProperty;
1919

2020
import io.swagger.v3.oas.annotations.media.Schema;
21+
import io.swagger.v3.oas.annotations.media.Schema.RequiredMode;
2122

2223
/**
2324
* Contributes to the model used for TSP swagger-core annotations.
@@ -30,26 +31,26 @@ public interface Bookmark {
3031
* @return The bookmark UUID.
3132
*/
3233
@JsonProperty("uuid")
33-
@Schema(description = "The bookmark's unique identifier")
34+
@Schema(description = "The bookmark's unique identifier", requiredMode = RequiredMode.REQUIRED)
3435
UUID getUUID();
3536

3637
/**
3738
* @return The bookmark name.
3839
*/
3940
@NonNull
40-
@Schema(description = "User defined name for the bookmark")
41+
@Schema(description = "User defined name for the bookmark", requiredMode = RequiredMode.REQUIRED)
4142
String getName();
4243

4344
/**
4445
* @return The start time.
4546
*/
46-
@Schema(description = "The bookmark's start time")
47+
@Schema(description = "The bookmark's start time", requiredMode = RequiredMode.REQUIRED)
4748
long getStart();
4849

4950
/**
5051
* @return The end time.
5152
*/
52-
@Schema(description = "The bookmark's end time")
53+
@Schema(description = "The bookmark's end time", requiredMode = RequiredMode.REQUIRED)
5354
long getEnd();
5455

5556
}

‎trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core/src/org/eclipse/tracecompass/incubator/internal/trace/server/jersey/rest/core/model/Configuration.java‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*******************************************************************************
2-
* Copyright (c) 2023, 2024 Ericsson
2+
* Copyright (c) 2023, 2025 Ericsson
33
*
44
* All rights reserved. This program and the accompanying materials are made
55
* available under the terms of the Eclipse Public License 2.0 which
@@ -15,6 +15,7 @@
1515

1616
import io.swagger.v3.oas.annotations.media.Schema;
1717
import io.swagger.v3.oas.annotations.media.Schema.AdditionalPropertiesValue;
18+
import io.swagger.v3.oas.annotations.media.Schema.RequiredMode;
1819

1920
/**
2021
* Contributes to the model used for TSP swagger-core annotations.
@@ -25,25 +26,25 @@ public interface Configuration {
2526
/**
2627
* @return the name of configuration instance
2728
*/
28-
@Schema(description = "The human readable name")
29+
@Schema(description = "The human readable name", requiredMode = RequiredMode.REQUIRED)
2930
String getName();
3031

3132
/**
3233
* @return the ID for of the configuration instance.
3334
*/
34-
@Schema(description = "The unique ID of the configuration instance")
35+
@Schema(description = "The unique ID of the configuration instance", requiredMode = RequiredMode.REQUIRED)
3536
String getId();
3637

3738
/**
3839
* @return a short description of this configuration instance.
3940
*/
40-
@Schema(description = "Describes the configuration instance")
41+
@Schema(description = "Optional, describes the configuration instance")
4142
String getDescription();
4243

4344
/**
4445
* @return the configuration source type
4546
*/
46-
@Schema(description = "The ID of the configuration source type")
47+
@Schema(description = "The ID of the configuration source type", requiredMode = RequiredMode.REQUIRED)
4748
String getSourceTypeId();
4849

4950
/**

‎trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core/src/org/eclipse/tracecompass/incubator/internal/trace/server/jersey/rest/core/model/ConfigurationParameterDescriptor.java‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*******************************************************************************
2-
* Copyright (c) 2023 Ericsson
2+
* Copyright (c) 2023, 2025 Ericsson
33
*
44
* All rights reserved. This program and the accompanying materials are made
55
* available under the terms of the Eclipse Public License 2.0 which
@@ -14,6 +14,7 @@
1414
import org.eclipse.jdt.annotation.NonNullByDefault;
1515

1616
import io.swagger.v3.oas.annotations.media.Schema;
17+
import io.swagger.v3.oas.annotations.media.Schema.RequiredMode;
1718

1819
/**
1920
* Contributes to the model used for TSP swagger-core annotations.
@@ -24,24 +25,24 @@ public interface ConfigurationParameterDescriptor {
2425
/**
2526
* @return the name of the configuration parameter
2627
*/
27-
@Schema(description = "The unique key name of the configuration parameter")
28+
@Schema(description = "The unique key name of the configuration parameter", requiredMode = RequiredMode.REQUIRED)
2829
String getKeyName();
2930

3031
/**
31-
* @return the ID for of the configuration parameter
32+
* @return data type hint of the configuration parameter
3233
*/
33-
@Schema(description = "The data type hint of the configuration parameter")
34+
@Schema(description = "Optional data type hint of the configuration parameter. For example, use NUMBER for numbers, or STRING as strings. If omitted assume the default value is STRING.")
3435
String getDataType();
3536

3637
/**
3738
* @return a short description of this configuration parameter
3839
*/
39-
@Schema(description = "Describes the configuration parameter")
40+
@Schema(description = "Optional, describes the configuration parameter")
4041
String getDescription();
4142

4243
/**
4344
* @return true if parameter is required else false.
4445
*/
45-
@Schema(description = "A flag indicating whether the configuration parameter is required or not")
46+
@Schema(description = "Optional flag indicating whether the configuration parameter is required or not. If ommitted the default value is false.")
4647
Boolean isRequired();
4748
}

‎trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core/src/org/eclipse/tracecompass/incubator/internal/trace/server/jersey/rest/core/model/ConfigurationSourceType.java‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*******************************************************************************
2-
* Copyright (c) 2023 Ericsson
2+
* Copyright (c) 2023, 2025 Ericsson
33
*
44
* All rights reserved. This program and the accompanying materials are made
55
* available under the terms of the Eclipse Public License 2.0 which
@@ -16,6 +16,7 @@
1616
import org.eclipse.jdt.annotation.NonNullByDefault;
1717

1818
import io.swagger.v3.oas.annotations.media.Schema;
19+
import io.swagger.v3.oas.annotations.media.Schema.RequiredMode;
1920

2021
/**
2122
* Contributes to the model used for TSP swagger-core annotations.
@@ -26,19 +27,19 @@ public interface ConfigurationSourceType {
2627
/**
2728
* @return the name of the configuration source type
2829
*/
29-
@Schema(description = "The human readable name")
30+
@Schema(description = "The human readable name", requiredMode = RequiredMode.REQUIRED)
3031
String getName();
3132

3233
/**
3334
* @return the ID for of the configuration source type
3435
*/
35-
@Schema(description = "The unique ID of the configuration source type")
36+
@Schema(description = "The unique ID of the configuration source type", requiredMode = RequiredMode.REQUIRED)
3637
String getId();
3738

3839
/**
3940
* @return a short description of this configuration source type
4041
*/
41-
@Schema(description = "Describes the configuration source type")
42+
@Schema(description = "Optional, describes the configuration source type")
4243
String getDescription();
4344

4445
/**

‎trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core/src/org/eclipse/tracecompass/incubator/internal/trace/server/jersey/rest/core/model/DataProvider.java‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212
package org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model;
1313

1414
import io.swagger.v3.oas.annotations.media.Schema;
15+
import io.swagger.v3.oas.annotations.media.Schema.RequiredMode;
1516

1617
/**
1718
* Contributes to the model used for TSP swagger-core annotations.
@@ -28,13 +29,13 @@ enum ProviderType {
2829
/**
2930
* @return The name.
3031
*/
31-
@Schema(description = "The human readable name")
32+
@Schema(description = "The human readable name", requiredMode = RequiredMode.REQUIRED)
3233
String getName();
3334

3435
/**
3536
* @return The ID.
3637
*/
37-
@Schema(description = "The output provider's ID")
38+
@Schema(description = "The output provider's ID", requiredMode = RequiredMode.REQUIRED)
3839
String getId();
3940

4041
/**
@@ -46,13 +47,14 @@ enum ProviderType {
4647
"Providers of type DATA_TREE only provide a tree with columns and don't have any XY nor time graph data associated with it. " +
4748
"Providers of type GANTT_CHART use the same endpoint as TIME_GRAPH, but have a different x-axis (duration, page faults, etc.), with their own separate ranges. " +
4849
"Providers of type TREE_GENERIC_XY supports XY view with non-time x-axis. " +
49-
"Providers of type NONE have no data to visualize. Can be used for grouping purposes and/or as data provider configurator.")
50+
"Providers of type NONE have no data to visualize. Can be used for grouping purposes and/or as data provider configurator.",
51+
requiredMode = RequiredMode.REQUIRED)
5052
ProviderType getType();
5153

5254
/**
5355
* @return The description.
5456
*/
55-
@Schema(description = "Describes the output provider's features")
57+
@Schema(description = "Describes the output provider's features", requiredMode = RequiredMode.REQUIRED)
5658
String getDescription();
5759

5860
/**

‎trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core/src/org/eclipse/tracecompass/incubator/internal/trace/server/jersey/rest/core/model/Experiment.java‎

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/**********************************************************************
2-
* Copyright (c) 2021 Ericsson
2+
* Copyright (c) 2021, 2025 Ericsson
33
*
44
* All rights reserved. This program and the accompanying materials are
55
* made available under the terms of the Eclipse Public License 2.0 which
@@ -18,6 +18,7 @@
1818

1919
import io.swagger.v3.oas.annotations.media.ArraySchema;
2020
import io.swagger.v3.oas.annotations.media.Schema;
21+
import io.swagger.v3.oas.annotations.media.Schema.RequiredMode;
2122

2223
/**
2324
* Contributes to the model used for TSP swagger-core annotations.
@@ -28,43 +29,43 @@ public interface Experiment {
2829
/**
2930
* @return The name.
3031
*/
31-
@Schema(description = "User defined name for the experiment")
32+
@Schema(description = "User defined name for the experiment", requiredMode = RequiredMode.REQUIRED)
3233
String getName();
3334

3435
/**
3536
* @return The UUID.
3637
*/
3738
@JsonProperty("UUID")
38-
@Schema(description = "The experiment's unique identifier")
39+
@Schema(description = "The experiment's unique identifier", requiredMode = RequiredMode.REQUIRED)
3940
UUID getUUID();
4041

4142
/**
4243
* @return The number of events.
4344
*/
44-
@Schema(description = "Current number of indexed events in the experiment")
45+
@Schema(description = "Current number of indexed events in the experiment", requiredMode = RequiredMode.REQUIRED)
4546
long getNbEvents();
4647

4748
/**
4849
* @return The start time.
4950
*/
50-
@Schema(description = "The experiment's start time")
51+
@Schema(description = "The experiment's start time", requiredMode = RequiredMode.REQUIRED)
5152
long getStart();
5253

5354
/**
5455
* @return The end time.
5556
*/
56-
@Schema(description = "The experiment's end time")
57+
@Schema(description = "The experiment's end time", requiredMode = RequiredMode.REQUIRED)
5758
long getEnd();
5859

5960
/**
6061
* @return The indexing status.
6162
*/
62-
@Schema(description = "Status of the experiment indexing")
63+
@Schema(description = "Status of the experiment indexing", requiredMode = RequiredMode.REQUIRED)
6364
IndexingStatus getIndexingStatus();
6465

6566
/**
6667
* @return The traces.
6768
*/
68-
@ArraySchema(arraySchema = @Schema(description = "The traces encapsulated by this experiment"))
69+
@ArraySchema(arraySchema = @Schema(description = "The traces encapsulated by this experiment"), schema = @Schema(requiredMode = RequiredMode.REQUIRED))
6970
List<Trace> getTraces();
7071
}

‎trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core/src/org/eclipse/tracecompass/incubator/internal/trace/server/jersey/rest/core/model/GenericResponse.java‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/**********************************************************************
2-
* Copyright (c) 2021 Ericsson
2+
* Copyright (c) 2021, 2025 Ericsson
33
*
44
* All rights reserved. This program and the accompanying materials are
55
* made available under the terms of the Eclipse Public License 2.0 which
@@ -12,6 +12,7 @@
1212
package org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model;
1313

1414
import io.swagger.v3.oas.annotations.media.Schema;
15+
import io.swagger.v3.oas.annotations.media.Schema.RequiredMode;
1516

1617
/**
1718
* Contributes to the model used for TSP swagger-core annotations.
@@ -30,10 +31,12 @@ enum Status {
3031
/**
3132
* @return The status.
3233
*/
34+
@Schema(requiredMode = RequiredMode.REQUIRED)
3335
Status getStatus();
3436

3537
/**
3638
* @return The status message.
3739
*/
40+
@Schema(requiredMode = RequiredMode.REQUIRED)
3841
String getStatusMessage();
3942
}

‎trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core/src/org/eclipse/tracecompass/incubator/internal/trace/server/jersey/rest/core/model/MarkerSet.java‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*******************************************************************************
2-
* Copyright (c) 2021 Ericsson
2+
* Copyright (c) 2021, 2025 Ericsson
33
*
44
* All rights reserved. This program and the accompanying materials are
55
* made available under the terms of the Eclipse Public License 2.0 which
@@ -12,6 +12,7 @@
1212
package org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model;
1313

1414
import io.swagger.v3.oas.annotations.media.Schema;
15+
import io.swagger.v3.oas.annotations.media.Schema.RequiredMode;
1516

1617
/**
1718
* Contributes to the model used for TSP swagger-core annotations.
@@ -22,12 +23,12 @@ public interface MarkerSet {
2223
/**
2324
* @return The name.
2425
*/
25-
@Schema(description = "Name of this marker set")
26+
@Schema(description = "Name of this marker set", requiredMode = RequiredMode.REQUIRED)
2627
String getName();
2728

2829
/**
2930
* @return The ID.
3031
*/
31-
@Schema(description = "ID of this marker set")
32+
@Schema(description = "ID of this marker set", requiredMode = RequiredMode.REQUIRED)
3233
String getId();
3334
}

‎trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core/src/org/eclipse/tracecompass/incubator/internal/trace/server/jersey/rest/core/model/OutputElementStyle.java‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/**********************************************************************
2-
* Copyright (c) 2021 Ericsson
2+
* Copyright (c) 2021, 2025 Ericsson
33
*
44
* All rights reserved. This program and the accompanying materials are
55
* made available under the terms of the Eclipse Public License 2.0 which
@@ -16,6 +16,7 @@
1616
import org.eclipse.jdt.annotation.Nullable;
1717

1818
import io.swagger.v3.oas.annotations.media.Schema;
19+
import io.swagger.v3.oas.annotations.media.Schema.RequiredMode;
1920

2021
/**
2122
* Contributes to the model used for TSP swagger-core annotations.
@@ -29,7 +30,7 @@ public interface OutputElementStyle {
2930
* @return The parent key.
3031
*/
3132
@Nullable
32-
@Schema(description = "Parent style key or empty if there is no parent. " +
33+
@Schema(description = "Optional, parent style key. If omitted there is no parent. " +
3334
"The parent key should match a style key defined in the style model and is used for style inheritance. " +
3435
"A comma-delimited list of parent style keys can be used for style composition, the last one taking precedence.")
3536
String getParentKey();
@@ -39,7 +40,8 @@ public interface OutputElementStyle {
3940
*/
4041
@Schema(description = "Style values or empty map if there are no values. " +
4142
"Keys and values are defined in " +
42-
"https://github.com/eclipse-tracecompass/org.eclipse.tracecompass/blob/master/tmf/org.eclipse.tracecompass.tmf.core/src/org/eclipse/tracecompass/tmf/core/model/StyleProperties.java")
43+
"https://github.com/eclipse-tracecompass/org.eclipse.tracecompass/blob/master/tmf/org.eclipse.tracecompass.tmf.core/src/org/eclipse/tracecompass/tmf/core/model/StyleProperties.java",
44+
requiredMode = RequiredMode.REQUIRED)
4345
Map<String, StyleValue> getValues();
4446

4547
/**

0 commit comments

Comments
 (0)