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 <[email protected]>
eclipse-tracecompass-incubator · Oct 29, 2024 · 5338473 · 5338473
1 parent 6074104
commit 5338473
Show file tree

Hide file tree

Showing 8 changed files with 61 additions and 54 deletions.
diff --git a/...cubator/trace/server/jersey/rest/core/tests/services/ConfigurationManagerServiceTest.java b/...cubator/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<String, Object> 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/...ipse/tracecompass/incubator/trace/server/jersey/rest/core/tests/utils/RestServerTest.java b/...ipse/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/...se/tracecompass/incubator/internal/trace/server/jersey/rest/core/model/Configuration.java b/...se/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/.../incubator/internal/trace/server/jersey/rest/core/model/ConfigurationQueryParameters.java b/.../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<String, Object> getParameters();
-    }
+    @Schema(required = true, description = "Parameters as specified in the schema or list of ConfigurationParameterDescriptor of the corresponding ConfigurationTypeDescriptor.")
+    Map<String, Object> getParameters();
 }
diff --git a/...ator/internal/trace/server/jersey/rest/core/model/OutputConfigurationQueryParameters.java b/...ator/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/...l/views/ConfigurationQueryParameters.java → ...ws/InputConfigurationQueryParameters.java b/...l/views/ConfigurationQueryParameters.java → ...ws/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<String, Object> parameters) {
+    public InputConfigurationQueryParameters(String name, String description, String typeId, Map<String, Object> 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/...ncubator/internal/trace/server/jersey/rest/core/services/ConfigurationManagerService.java b/...ncubator/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/...ompass/incubator/internal/trace/server/jersey/rest/core/services/DataProviderService.java b/...ompass/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();
         }