From 5338473bf0f9f0f8ebba255053cde6cc1fca341f Mon Sep 17 00:00:00 2001 From: Bernd Hufmann Date: Tue, 29 Oct 2024 13:59:10 -0400 Subject: [PATCH] swagger: Fix swagger annotations for global and output configurations The documentation didn't match the implementation. This PR fixes this. Rename the implementation class ConfigurationQueryParameters to InputConfigurationQueryParameters because for some reason it's put into the swagger documentation and before it classed with the swagger doc class for ConfigurationQueryParameters, and hence it was incorrect. Note that InputConfigurationQueryParameters needs to be manually removed from the generated swagger doc. Signed-off-by: Bernd Hufmann --- .../ConfigurationManagerServiceTest.java | 8 ++-- .../rest/core/tests/utils/RestServerTest.java | 6 +-- .../jersey/rest/core/model/Configuration.java | 3 +- .../model/ConfigurationQueryParameters.java | 47 +++++-------------- .../OutputConfigurationQueryParameters.java | 29 ++++++++++++ ...=> InputConfigurationQueryParameters.java} | 6 +-- .../services/ConfigurationManagerService.java | 6 +-- .../core/services/DataProviderService.java | 10 ++-- 8 files changed, 61 insertions(+), 54 deletions(-) create mode 100644 trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core/src/org/eclipse/tracecompass/incubator/internal/trace/server/jersey/rest/core/model/OutputConfigurationQueryParameters.java rename trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core/src/org/eclipse/tracecompass/incubator/internal/trace/server/jersey/rest/core/model/views/{ConfigurationQueryParameters.java => InputConfigurationQueryParameters.java} (92%) diff --git a/trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core.tests/src/org/eclipse/tracecompass/incubator/trace/server/jersey/rest/core/tests/services/ConfigurationManagerServiceTest.java b/trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core.tests/src/org/eclipse/tracecompass/incubator/trace/server/jersey/rest/core/tests/services/ConfigurationManagerServiceTest.java index 9b29ce1f..dbc9f1f9 100644 --- a/trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core.tests/src/org/eclipse/tracecompass/incubator/trace/server/jersey/rest/core/tests/services/ConfigurationManagerServiceTest.java +++ b/trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core.tests/src/org/eclipse/tracecompass/incubator/trace/server/jersey/rest/core/tests/services/ConfigurationManagerServiceTest.java @@ -38,7 +38,7 @@ import org.eclipse.core.runtime.Platform; import org.eclipse.jdt.annotation.NonNull; import org.eclipse.jdt.annotation.Nullable; -import org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model.views.ConfigurationQueryParameters; +import org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model.views.InputConfigurationQueryParameters; import org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model.views.QueryParameters; import org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.services.ConfigurationManagerService; import org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core.tests.stubs.ExperimentModelStub; @@ -358,7 +358,7 @@ private static Response createConfig(String path, boolean isCorrectType) { parameters.put(PATH, path); } return endpoint.request(MediaType.APPLICATION_JSON) - .post(Entity.json(new ConfigurationQueryParameters(null, null, null, parameters))); + .post(Entity.json(new InputConfigurationQueryParameters(null, null, null, parameters))); } private static Response createJsonConfig(String jsonFileName) throws URISyntaxException, IOException { @@ -371,7 +371,7 @@ private static Response createJsonConfig(String jsonFileName) throws URISyntaxEx Map params = readParametersFromJson(jsonFileName); return endpoint.request(MediaType.APPLICATION_JSON) - .post(Entity.json(new ConfigurationQueryParameters(null, null, null, params))); + .post(Entity.json(new InputConfigurationQueryParameters(null, null, null, params))); } private static Response updateConfig(String path, String id) { @@ -403,7 +403,7 @@ private static Response updateConfig(String path, String id, boolean isCorrectTy parameters.put(PATH, path); } return endpoint.request(MediaType.APPLICATION_JSON) - .put(Entity.json(new ConfigurationQueryParameters(null, null, null, parameters))); + .put(Entity.json(new InputConfigurationQueryParameters(null, null, null, parameters))); } private static Response deleteConfig(String id) { diff --git a/trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core.tests/src/org/eclipse/tracecompass/incubator/trace/server/jersey/rest/core/tests/utils/RestServerTest.java b/trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core.tests/src/org/eclipse/tracecompass/incubator/trace/server/jersey/rest/core/tests/utils/RestServerTest.java index 94cc41d1..7d1cdc6d 100644 --- a/trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core.tests/src/org/eclipse/tracecompass/incubator/trace/server/jersey/rest/core/tests/utils/RestServerTest.java +++ b/trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core.tests/src/org/eclipse/tracecompass/incubator/trace/server/jersey/rest/core/tests/utils/RestServerTest.java @@ -37,7 +37,7 @@ import org.eclipse.core.runtime.FileLocator; import org.eclipse.core.runtime.IPath; import org.eclipse.core.runtime.Platform; -import org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model.views.ConfigurationQueryParameters; +import org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model.views.InputConfigurationQueryParameters; import org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model.views.QueryParameters; import org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.webapp.TraceServerConfiguration; import org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.webapp.WebApplication; @@ -627,7 +627,7 @@ public static ExperimentModelStub assertPostExperiment(String name, TraceModelSt @SuppressWarnings("null") public static DataProviderDescriptorStub assertDpPost(WebTarget dpConfigEndpoint, ITmfConfiguration configuration) { try (Response response = dpConfigEndpoint.request().post(Entity.json( - new ConfigurationQueryParameters(configuration.getName(), configuration.getDescription(), configuration.getSourceTypeId(), configuration.getParameters())))) { + new InputConfigurationQueryParameters(configuration.getName(), configuration.getDescription(), configuration.getSourceTypeId(), configuration.getParameters())))) { int code = response.getStatus(); assertEquals("Failed to POST " + configuration.getName() + ", error code=" + code, 200, code); DataProviderDescriptorStub result = response.readEntity(DataProviderDescriptorStub.class); @@ -651,7 +651,7 @@ public static DataProviderDescriptorStub assertDpPost(WebTarget dpConfigEndpoint @SuppressWarnings("null") public static Response assertDpPostWithErrors(WebTarget dpConfigEndpoint, ITmfConfiguration configuration) { return dpConfigEndpoint.request().post(Entity.json( - new ConfigurationQueryParameters(configuration.getName(), configuration.getDescription(), configuration.getSourceTypeId(), configuration.getParameters()))); + new InputConfigurationQueryParameters(configuration.getName(), configuration.getDescription(), configuration.getSourceTypeId(), configuration.getParameters()))); } /** diff --git a/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 b/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 index 5fd16bab..f5c96507 100644 --- a/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 +++ b/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 @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2023 Ericsson + * Copyright (c) 2023, 2024 Ericsson * * All rights reserved. This program and the accompanying materials are made * available under the terms of the Eclipse Public License 2.0 which @@ -21,6 +21,7 @@ * Contributes to the model used for TSP swagger-core annotations. */ @NonNullByDefault +@Schema(description = "Configuration instance describing user provided configuration parameters.") public interface Configuration { /** * @return the name of configuration instance diff --git a/trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core/src/org/eclipse/tracecompass/incubator/internal/trace/server/jersey/rest/core/model/ConfigurationQueryParameters.java b/trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core/src/org/eclipse/tracecompass/incubator/internal/trace/server/jersey/rest/core/model/ConfigurationQueryParameters.java index 097dc2d0..11a0946f 100644 --- a/trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core/src/org/eclipse/tracecompass/incubator/internal/trace/server/jersey/rest/core/model/ConfigurationQueryParameters.java +++ b/trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core/src/org/eclipse/tracecompass/incubator/internal/trace/server/jersey/rest/core/model/ConfigurationQueryParameters.java @@ -1,5 +1,5 @@ /********************************************************************** - * Copyright (c) 2023 Ericsson + * Copyright (c) 2024 Ericsson * * All rights reserved. This program and the accompanying materials are * made available under the terms of the Eclipse Public License 2.0 which @@ -13,48 +13,25 @@ import java.util.Map; -import org.eclipse.jdt.annotation.NonNull; - -import com.fasterxml.jackson.annotation.JsonProperty; - import io.swagger.v3.oas.annotations.media.Schema; /** * Contributes to the model used for TSP swagger-core annotations. */ public interface ConfigurationQueryParameters { - /** - * @return The parameters. + * @return the name of the configuration */ - @NonNull - @Schema(required = true) - ConfigurationParameters getParameters(); - + @Schema(required = true, description = "Unique name of the configuration.") + String getName(); + /** + * @return the description of the configuration + */ + @Schema(required = false, description = "Optional description of the configuration.") + String getDescription(); /** - * Configuration parameters as per current trace-server protocol. + * @return parameters map for custom parameters as defined in the corresponding {@link ConfigurationSourceType} */ - interface ConfigurationParameters { - /** - * @return the name of the configuration - */ - @Schema(required = true, description = "Unique name of the configuration. If omitted a unique name will be generated.") - String getName(); - /** - * @return the description of the configuration - */ - @Schema(required = false, description = "Optional description of the configuration.") - String getDescription(); - /** - * @return the typeId of the configuration according to the {@link ConfigurationSourceType} - */ - @Schema(required = false, description = "Optional typeId of the configuration according to the corresponding ConfigurationTypeDescriptor. Omit if it's part of the endpoint URI.") - @JsonProperty("typeId") - String getTypeId(); - /** - * @return parameters map for custom parameters as defined in the corresponding {@link ConfigurationSourceType} - */ - @Schema(required = true, description = "Parameters as specified in the schema or list of ConfigurationParameterDescriptor of the corresponding ConfigurationTypeDescriptor.") - Map getParameters(); - } + @Schema(required = true, description = "Parameters as specified in the schema or list of ConfigurationParameterDescriptor of the corresponding ConfigurationTypeDescriptor.") + Map getParameters(); } diff --git a/trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core/src/org/eclipse/tracecompass/incubator/internal/trace/server/jersey/rest/core/model/OutputConfigurationQueryParameters.java b/trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core/src/org/eclipse/tracecompass/incubator/internal/trace/server/jersey/rest/core/model/OutputConfigurationQueryParameters.java new file mode 100644 index 00000000..caf6561f --- /dev/null +++ b/trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core/src/org/eclipse/tracecompass/incubator/internal/trace/server/jersey/rest/core/model/OutputConfigurationQueryParameters.java @@ -0,0 +1,29 @@ +/********************************************************************** + * Copyright (c) 2023, 2024 Ericsson + * + * All rights reserved. This program and the accompanying materials are + * made available under the terms of the Eclipse Public License 2.0 which + * accompanies this distribution, and is available at + * https://www.eclipse.org/legal/epl-2.0/ + * + * SPDX-License-Identifier: EPL-2.0 + **********************************************************************/ + +package org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model; + +import com.fasterxml.jackson.annotation.JsonProperty; + +import io.swagger.v3.oas.annotations.media.Schema; + +/** + * Contributes to the model used for TSP swagger-core annotations. + */ +public interface OutputConfigurationQueryParameters extends ConfigurationQueryParameters { + /** + * @return the typeId of the configuration according to the + * {@link ConfigurationSourceType} + */ + @Schema(required = true, description = "TypeId of the configuration according to the corresponding ConfigurationTypeDescriptor.") + @JsonProperty("typeId") + String getTypeId(); +} diff --git a/trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core/src/org/eclipse/tracecompass/incubator/internal/trace/server/jersey/rest/core/model/views/ConfigurationQueryParameters.java b/trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core/src/org/eclipse/tracecompass/incubator/internal/trace/server/jersey/rest/core/model/views/InputConfigurationQueryParameters.java similarity index 92% rename from trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core/src/org/eclipse/tracecompass/incubator/internal/trace/server/jersey/rest/core/model/views/ConfigurationQueryParameters.java rename to trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core/src/org/eclipse/tracecompass/incubator/internal/trace/server/jersey/rest/core/model/views/InputConfigurationQueryParameters.java index 78b208c1..09873e17 100644 --- a/trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core/src/org/eclipse/tracecompass/incubator/internal/trace/server/jersey/rest/core/model/views/ConfigurationQueryParameters.java +++ b/trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core/src/org/eclipse/tracecompass/incubator/internal/trace/server/jersey/rest/core/model/views/InputConfigurationQueryParameters.java @@ -20,7 +20,7 @@ /** * Definition of a parameters object received by the server from a client for configurations. */ -public class ConfigurationQueryParameters { +public class InputConfigurationQueryParameters { private @NonNull String name; private @NonNull String description; private @NonNull String typeId; @@ -29,7 +29,7 @@ public class ConfigurationQueryParameters { /** * Constructor for Jackson */ - public ConfigurationQueryParameters() { + public InputConfigurationQueryParameters() { // Default constructor for Jackson this.parameters = new HashMap<>(); @@ -51,7 +51,7 @@ public ConfigurationQueryParameters() { * @param parameters * Map of parameters */ - public ConfigurationQueryParameters(String name, String description, String typeId, Map parameters) { + public InputConfigurationQueryParameters(String name, String description, String typeId, Map parameters) { this.parameters = parameters != null ? parameters : new HashMap<>(); this.name = name == null ? TmfConfiguration.UNKNOWN : name; this.description = description == null ? TmfConfiguration.UNKNOWN : description; diff --git a/trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core/src/org/eclipse/tracecompass/incubator/internal/trace/server/jersey/rest/core/services/ConfigurationManagerService.java b/trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core/src/org/eclipse/tracecompass/incubator/internal/trace/server/jersey/rest/core/services/ConfigurationManagerService.java index 947dad6c..4cf2c4d9 100644 --- a/trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core/src/org/eclipse/tracecompass/incubator/internal/trace/server/jersey/rest/core/services/ConfigurationManagerService.java +++ b/trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core/src/org/eclipse/tracecompass/incubator/internal/trace/server/jersey/rest/core/services/ConfigurationManagerService.java @@ -31,7 +31,7 @@ import javax.ws.rs.core.Response; import javax.ws.rs.core.Response.Status; -import org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model.views.ConfigurationQueryParameters; +import org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model.views.InputConfigurationQueryParameters; import org.eclipse.tracecompass.tmf.core.config.ITmfConfiguration; import org.eclipse.tracecompass.tmf.core.config.ITmfConfigurationSource; import org.eclipse.tracecompass.tmf.core.config.TmfConfiguration; @@ -144,7 +144,7 @@ public Response postConfiguration(@Parameter(description = CFG_TYPE_ID) @PathPar @RequestBody(description = CFG_CREATE_DESC + " " + CFG_KEYS_DESC, content = { @Content(examples = @ExampleObject("{\"parameters\":{" + CFG_PATH_EX + "}}"), schema = @Schema(implementation = org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model.ConfigurationQueryParameters.class)) - }, required = true) ConfigurationQueryParameters queryParameters) { + }, required = true) InputConfigurationQueryParameters queryParameters) { ITmfConfigurationSource configurationSource = fConfigSourceManager.getConfigurationSource(typeId); if (configurationSource == null) { return Response.status(Status.NOT_FOUND).entity("Configuration source type doesn't exist").build(); //$NON-NLS-1$ @@ -225,7 +225,7 @@ public Response putConfiguration(@Parameter(description = CFG_TYPE_ID) @PathPara @RequestBody(description = CFG_UPDATE_DESC + " " + CFG_KEYS_DESC, content = { @Content(examples = @ExampleObject("{\"parameters\":{" + CFG_PATH_EX + "}}"), schema = @Schema(implementation = org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model.ConfigurationQueryParameters.class)) - }, required = true) ConfigurationQueryParameters queryParameters) { + }, required = true) InputConfigurationQueryParameters queryParameters) { ITmfConfigurationSource configurationSource = fConfigSourceManager.getConfigurationSource(typeId); if (configurationSource == null) { return Response.status(Status.NOT_FOUND).entity("Configuration source type doesn't exist").build(); //$NON-NLS-1$ diff --git a/trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core/src/org/eclipse/tracecompass/incubator/internal/trace/server/jersey/rest/core/services/DataProviderService.java b/trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core/src/org/eclipse/tracecompass/incubator/internal/trace/server/jersey/rest/core/services/DataProviderService.java index e1503009..b2ff4823 100644 --- a/trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core/src/org/eclipse/tracecompass/incubator/internal/trace/server/jersey/rest/core/services/DataProviderService.java +++ b/trace-server/org.eclipse.tracecompass.incubator.trace.server.jersey.rest.core/src/org/eclipse/tracecompass/incubator/internal/trace/server/jersey/rest/core/services/DataProviderService.java @@ -123,7 +123,7 @@ import org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model.VirtualTableResponse; import org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model.XYResponse; import org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model.XYTreeResponse; -import org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model.views.ConfigurationQueryParameters; +import org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model.views.InputConfigurationQueryParameters; import org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model.views.GenericView; import org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model.views.QueryParameters; import org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model.views.TableColumnHeader; @@ -1256,7 +1256,7 @@ public Response getConfigurationType( @Tag(name = OCG) @Consumes(MediaType.APPLICATION_JSON) @Produces(MediaType.APPLICATION_JSON) - @Operation(summary = "Get the list of outputs for this configuration", responses = { + @Operation(summary = "Get a derived data provider from a input configuration", responses = { @ApiResponse(responseCode = "200", description = "Returns a list of output provider descriptors", content = @Content(array = @ArraySchema(schema = @Schema(implementation = DataProvider.class)))), @ApiResponse(responseCode = "400", description = INVALID_PARAMETERS, content = @Content(schema = @Schema(implementation = String.class))), @ApiResponse(responseCode = "404", description = PROVIDER_CONFIG_NOT_FOUND, content = @Content(schema = @Schema(implementation = String.class))), @@ -1265,8 +1265,8 @@ public Response createDataProvider( @Parameter(description = EXP_UUID) @PathParam("expUUID") UUID expUUID, @Parameter(description = OUTPUT_ID) @PathParam("outputId") String outputId, @RequestBody(description = CFG_CREATE_DESC + " " + CFG_KEYS_DESC, content = { - @Content(schema = @Schema(implementation = org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model.ConfigurationQueryParameters.class)) - }, required = true) ConfigurationQueryParameters queryParameters) { + @Content(schema = @Schema(implementation = org.eclipse.tracecompass.incubator.internal.trace.server.jersey.rest.core.model.OutputConfigurationQueryParameters.class)) + }, required = true) InputConfigurationQueryParameters queryParameters) { try (FlowScopeLog scope = new FlowScopeLogBuilder(LOGGER, Level.FINE, "DataProviderService#createDataProvider") //$NON-NLS-1$ .setCategory(outputId).build()) { @@ -1384,7 +1384,7 @@ private static Response validateParameters(String outputId, QueryParameters quer return null; } - private static Response validateOutputConfigParameters(String outputId, ConfigurationQueryParameters queryParameters) { + private static Response validateOutputConfigParameters(String outputId, InputConfigurationQueryParameters queryParameters) { if (outputId == null) { return Response.status(Status.BAD_REQUEST).entity(MISSING_OUTPUTID).build(); }