docs(api): fix request and response types

extensions/common/api/version-api/src/main/java/org/eclipse/edc/connector/api/management/version/v1/VersionApi.java

@@ -39,7 +39,6 @@
 public interface VersionApi {
 
  @Operation(description = "Gets the exact SemVer string of the Management API",
- operationId = "getVersion",
  responses = {
  @ApiResponse(responseCode = "200", description = "The secret",
  content = @Content(schema = @Schema(implementation = SecretOutputSchema.class)))

extensions/control-plane/api/management-api/asset-api/src/main/java/org/eclipse/edc/connector/controlplane/api/management/asset/v3/AssetApi.java

@@ -40,7 +40,6 @@
 @Tag(name = "Asset V3")
 public interface AssetApi {
  @Operation(description = "Creates a new asset together with a data address",
- operationId = "createAssetV3",
  requestBody = @RequestBody(content = @Content(schema = @Schema(implementation = AssetInputSchema.class))),
  responses = {
  @ApiResponse(responseCode = "200", description = "Asset was created successfully. Returns the asset Id and created timestamp",
@@ -50,10 +49,9 @@ public interface AssetApi {
  @ApiResponse(responseCode = "409", description = "Could not create asset, because an asset with that ID already exists",
  content = @Content(array = @ArraySchema(schema = @Schema(implementation = ApiCoreSchema.ApiErrorDetailSchema.class)))) }
  )
- JsonObject createAsset(JsonObject asset);
+ JsonObject createAssetV3(JsonObject asset);
 
  @Operation(description = "Request all assets according to a particular query",
- operationId = "requestAssetV3",
  requestBody = @RequestBody(
  content = @Content(schema = @Schema(implementation = ApiCoreSchema.QuerySpecSchema.class))
  ),
@@ -63,10 +61,9 @@ public interface AssetApi {
  @ApiResponse(responseCode = "400", description = "Request body was malformed",
  content = @Content(array = @ArraySchema(schema = @Schema(implementation = ApiCoreSchema.ApiErrorDetailSchema.class))))
  })
- JsonArray requestAssets(JsonObject querySpecJson);
+ JsonArray requestAssetsV3(JsonObject querySpecJson);
 
  @Operation(description = "Gets an asset with the given ID",
- operationId = "getAssetV3",
  responses = {
  @ApiResponse(responseCode = "200", description = "The asset",
  content = @Content(schema = @Schema(implementation = AssetOutputSchema.class))),
@@ -76,12 +73,11 @@ public interface AssetApi {
  content = @Content(array = @ArraySchema(schema = @Schema(implementation = ApiCoreSchema.ApiErrorDetailSchema.class))))
  }
  )
- JsonObject getAsset(String id);
+ JsonObject getAssetV3(String id);
 
  @Operation(description = "Removes an asset with the given ID if possible. Deleting an asset is only possible if that asset is not yet referenced " +
  "by a contract agreement, in which case an error is returned. " +
  "DANGER ZONE: Note that deleting assets can have unexpected results, especially for contract offers that have been sent out or ongoing or contract negotiations.",
- operationId = "removeAssetV3",
  responses = {
  @ApiResponse(responseCode = "204", description = "Asset was deleted successfully"),
  @ApiResponse(responseCode = "400", description = "Request was malformed, e.g. id was null",
@@ -91,19 +87,18 @@ public interface AssetApi {
  @ApiResponse(responseCode = "409", description = "The asset cannot be deleted, because it is referenced by a contract agreement",
  content = @Content(array = @ArraySchema(schema = @Schema(implementation = ApiCoreSchema.ApiErrorDetailSchema.class))))
  })
- void removeAsset(String id);
+ void removeAssetV3(String id);
 
  @Operation(description = "Updates an asset with the given ID if it exists. If the asset is not found, no further action is taken. " +
  "DANGER ZONE: Note that updating assets can have unexpected results, especially for contract offers that have been sent out or are ongoing in contract negotiations.",
- operationId = "updateAssetV3",
  requestBody = @RequestBody(content = @Content(schema = @Schema(implementation = AssetInputSchema.class))),
  responses = {
  @ApiResponse(responseCode = "204", description = "Asset was updated successfully"),
  @ApiResponse(responseCode = "404", description = "Asset could not be updated, because it does not exist."),
  @ApiResponse(responseCode = "400", description = "Request was malformed, e.g. id was null",
  content = @Content(array = @ArraySchema(schema = @Schema(implementation = ApiCoreSchema.ApiErrorDetailSchema.class)))),
  })
- void updateAsset(JsonObject asset);
+ void updateAssetV3(JsonObject asset);
 
  @Schema(name = "AssetInput", example = AssetInputSchema.ASSET_INPUT_EXAMPLE)
  record AssetInputSchema(

extensions/control-plane/api/management-api/asset-api/src/main/java/org/eclipse/edc/connector/controlplane/api/management/asset/v3/AssetApiController.java

@@ -63,7 +63,7 @@ public AssetApiController(AssetService service, TypeTransformerRegistry transfor
 
  @POST
  @Override
- public JsonObject createAsset(JsonObject assetJson) {
+ public JsonObject createAssetV3(JsonObject assetJson) {
  validator.validate(EDC_ASSET_TYPE, assetJson).orElseThrow(ValidationFailureException::new);
 
  var asset = transformerRegistry.transform(assetJson, Asset.class)
@@ -83,7 +83,7 @@ public JsonObject createAsset(JsonObject assetJson) {
  @POST
  @Path("/request")
  @Override
- public JsonArray requestAssets(JsonObject querySpecJson) {
+ public JsonArray requestAssetsV3(JsonObject querySpecJson) {
  QuerySpec querySpec;
  if (querySpecJson == null) {
  querySpec = QuerySpec.Builder.newInstance().build();
@@ -105,7 +105,7 @@ public JsonArray requestAssets(JsonObject querySpecJson) {
  @GET
  @Path("{id}")
  @Override
- public JsonObject getAsset(@PathParam("id") String id) {
+ public JsonObject getAssetV3(@PathParam("id") String id) {
  var asset = of(id)
  .map(it -> service.findById(id))
  .orElseThrow(() -> new ObjectNotFoundException(Asset.class, id));
@@ -118,13 +118,13 @@ public JsonObject getAsset(@PathParam("id") String id) {
  @DELETE
  @Path("{id}")
  @Override
- public void removeAsset(@PathParam("id") String id) {
+ public void removeAssetV3(@PathParam("id") String id) {
  service.delete(id).orElseThrow(exceptionMapper(Asset.class, id));
  }
 
  @PUT
  @Override
- public void updateAsset(JsonObject assetJson) {
+ public void updateAssetV3(JsonObject assetJson) {
  validator.validate(EDC_ASSET_TYPE, assetJson).orElseThrow(ValidationFailureException::new);
 
  var assetResult = transformerRegistry.transform(assetJson, Asset.class)

extensions/control-plane/api/management-api/catalog-api/src/main/java/org/eclipse/edc/connector/controlplane/api/management/catalog/BaseCatalogApiController.java

@@ -15,12 +15,7 @@
 package org.eclipse.edc.connector.controlplane.api.management.catalog;
 
 import jakarta.json.JsonObject;
-import jakarta.ws.rs.Consumes;
-import jakarta.ws.rs.POST;
-import jakarta.ws.rs.Path;
-import jakarta.ws.rs.Produces;
 import jakarta.ws.rs.container.AsyncResponse;
-import jakarta.ws.rs.container.Suspended;
 import org.eclipse.edc.connector.controlplane.catalog.spi.CatalogRequest;
 import org.eclipse.edc.connector.controlplane.catalog.spi.DatasetRequest;
 import org.eclipse.edc.connector.controlplane.services.spi.catalog.CatalogService;
@@ -32,12 +27,10 @@
 import org.eclipse.edc.web.spi.exception.InvalidRequestException;
 import org.eclipse.edc.web.spi.exception.ValidationFailureException;
 
-import static jakarta.ws.rs.core.MediaType.APPLICATION_JSON;
 import static org.eclipse.edc.connector.controlplane.catalog.spi.CatalogRequest.CATALOG_REQUEST_TYPE;
 import static org.eclipse.edc.connector.controlplane.catalog.spi.DatasetRequest.DATASET_REQUEST_TYPE;
 
-@Consumes(APPLICATION_JSON)
-@Produces(APPLICATION_JSON)
+
 public abstract class BaseCatalogApiController {
 
  private final CatalogService service;
@@ -51,9 +44,7 @@ public BaseCatalogApiController(CatalogService service, TypeTransformerRegistry
  this.validatorRegistry = validatorRegistry;
  }
 
- @POST
- @Path("/request")
- public void requestCatalog(JsonObject requestBody, @Suspended AsyncResponse response) {
+ public void requestCatalog(JsonObject requestBody, AsyncResponse response) {
  validatorRegistry.validate(CATALOG_REQUEST_TYPE, requestBody).orElseThrow(ValidationFailureException::new);
 
  var request = transformerRegistry.transform(requestBody, CatalogRequest.class)
@@ -69,9 +60,7 @@ public void requestCatalog(JsonObject requestBody, @Suspended AsyncResponse resp
  });
  }
 
- @POST
- @Path("dataset/request")
- public void getDataset(JsonObject requestBody, @Suspended AsyncResponse response) {
+ public void getDataset(JsonObject requestBody, AsyncResponse response) {
  validatorRegistry.validate(DATASET_REQUEST_TYPE, requestBody).orElseThrow(ValidationFailureException::new);
 
  var request = transformerRegistry.transform(requestBody, DatasetRequest.class)

extensions/control-plane/api/management-api/catalog-api/src/main/java/org/eclipse/edc/connector/controlplane/api/management/catalog/v2/CatalogApiV2.java

@@ -39,7 +39,6 @@ public interface CatalogApiV2 {
 
  @Operation(
  requestBody = @RequestBody(content = @Content(schema = @Schema(implementation = CatalogRequestSchema.class))),
- operationId = "requestCatalogV2",
  responses = { @ApiResponse(
  content = @Content(
  mediaType = "application/json",
@@ -49,11 +48,10 @@ public interface CatalogApiV2 {
  deprecated = true
  )
  @Deprecated(since = "0.7.0")
- void requestCatalog(JsonObject request, @Suspended AsyncResponse response);
+ void requestCatalogV2(JsonObject request, @Suspended AsyncResponse response);
 
  @Operation(
  requestBody = @RequestBody(content = @Content(schema = @Schema(implementation = DatasetRequestSchema.class))),
- operationId = "getDatasetV2",
  responses = { @ApiResponse(
  content = @Content(
  mediaType = "application/json",
@@ -63,7 +61,7 @@ public interface CatalogApiV2 {
  deprecated = true
  )
  @Deprecated(since = "0.7.0")
- void getDataset(JsonObject request, @Suspended AsyncResponse response);
+ void getDatasetV2(JsonObject request, @Suspended AsyncResponse response);
 
  @Schema(name = "CatalogRequest", example = CatalogRequestSchema.CATALOG_REQUEST_EXAMPLE)
  record CatalogRequestSchema(

extensions/control-plane/api/management-api/catalog-api/src/main/java/org/eclipse/edc/connector/controlplane/api/management/catalog/v2/CatalogApiV2Controller.java

@@ -15,15 +15,23 @@
 package org.eclipse.edc.connector.controlplane.api.management.catalog.v2;
 
 import jakarta.json.JsonObject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.POST;
 import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
 import jakarta.ws.rs.container.AsyncResponse;
-import org.eclipse.edc.api.ApiWarnings;
+import jakarta.ws.rs.container.Suspended;
 import org.eclipse.edc.connector.controlplane.api.management.catalog.BaseCatalogApiController;
 import org.eclipse.edc.connector.controlplane.services.spi.catalog.CatalogService;
 import org.eclipse.edc.spi.monitor.Monitor;
 import org.eclipse.edc.transform.spi.TypeTransformerRegistry;
 import org.eclipse.edc.validator.spi.JsonObjectValidatorRegistry;
 
+import static jakarta.ws.rs.core.MediaType.APPLICATION_JSON;
+import static org.eclipse.edc.api.ApiWarnings.deprecationWarning;
+
+@Consumes(APPLICATION_JSON)
+@Produces(APPLICATION_JSON)
 @Path("/v2/catalog")
 public class CatalogApiV2Controller extends BaseCatalogApiController implements CatalogApiV2 {
  private final Monitor monitor;
@@ -33,15 +41,19 @@ public CatalogApiV2Controller(CatalogService service, TypeTransformerRegistry tr
  this.monitor = monitor;
  }
 
+ @POST
+ @Path("/request")
  @Override
- public void requestCatalog(JsonObject requestBody, AsyncResponse response) {
- monitor.warning(ApiWarnings.deprecationWarning("/v2", "/v3"));
- super.requestCatalog(requestBody, response);
+ public void requestCatalogV2(JsonObject requestBody, @Suspended AsyncResponse response) {
+ monitor.warning(deprecationWarning("/v2", "/v3"));
+ requestCatalog(requestBody, response);
  }
 
+ @POST
+ @Path("dataset/request")
  @Override
- public void getDataset(JsonObject requestBody, AsyncResponse response) {
- monitor.warning(ApiWarnings.deprecationWarning("/v2", "/v3"));
- super.getDataset(requestBody, response);
+ public void getDatasetV2(JsonObject requestBody, @Suspended AsyncResponse response) {
+ monitor.warning(deprecationWarning("/v2", "/v3"));
+ getDataset(requestBody, response);
  }
 }

extensions/control-plane/api/management-api/catalog-api/src/main/java/org/eclipse/edc/connector/controlplane/api/management/catalog/v3/CatalogApiV3.java

@@ -39,27 +39,25 @@ public interface CatalogApiV3 {
 
  @Operation(
  requestBody = @RequestBody(content = @Content(schema = @Schema(implementation = CatalogRequestSchema.class))),
- operationId = "requestCatalogV3",
  responses = { @ApiResponse(
  content = @Content(
  mediaType = "application/json",
  schema = @Schema(implementation = CatalogSchema.class)
  ),
  description = "Gets contract offers (=catalog) of a single connector") }
  )
- void requestCatalog(JsonObject request, @Suspended AsyncResponse response);
+ void requestCatalogV3(JsonObject request, @Suspended AsyncResponse response);
 
  @Operation(
  requestBody = @RequestBody(content = @Content(schema = @Schema(implementation = DatasetRequestSchema.class))),
- operationId = "getDatasetV3",
  responses = { @ApiResponse(
  content = @Content(
  mediaType = "application/json",
  schema = @Schema(implementation = DatasetSchema.class)
  ),
  description = "Gets single dataset from a connector") }
  )
- void getDataset(JsonObject request, @Suspended AsyncResponse response);
+ void getDatasetV3(JsonObject request, @Suspended AsyncResponse response);
 
  @Schema(name = "CatalogRequest", example = CatalogRequestSchema.CATALOG_REQUEST_EXAMPLE)
  record CatalogRequestSchema(

extensions/control-plane/api/management-api/catalog-api/src/main/java/org/eclipse/edc/connector/controlplane/api/management/catalog/v3/CatalogApiV3Controller.java

@@ -14,15 +14,39 @@
 
 package org.eclipse.edc.connector.controlplane.api.management.catalog.v3;
 
+import jakarta.json.JsonObject;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.POST;
 import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.container.AsyncResponse;
+import jakarta.ws.rs.container.Suspended;
 import org.eclipse.edc.connector.controlplane.api.management.catalog.BaseCatalogApiController;
 import org.eclipse.edc.connector.controlplane.services.spi.catalog.CatalogService;
 import org.eclipse.edc.transform.spi.TypeTransformerRegistry;
 import org.eclipse.edc.validator.spi.JsonObjectValidatorRegistry;
 
+import static jakarta.ws.rs.core.MediaType.APPLICATION_JSON;
+
+@Consumes(APPLICATION_JSON)
+@Produces(APPLICATION_JSON)
 @Path("/v3/catalog")
 public class CatalogApiV3Controller extends BaseCatalogApiController implements CatalogApiV3 {
  public CatalogApiV3Controller(CatalogService service, TypeTransformerRegistry transformerRegistry, JsonObjectValidatorRegistry validatorRegistry) {
  super(service, transformerRegistry, validatorRegistry);
  }
+
+ @POST
+ @Path("/request")
+ @Override
+ public void requestCatalogV3(JsonObject request, @Suspended AsyncResponse response) {
+ requestCatalog(request, response);
+ }
+
+ @POST
+ @Path("dataset/request")
+ @Override
+ public void getDatasetV3(JsonObject request, @Suspended AsyncResponse response) {
+ getDataset(request, response);
+ }
 }

extensions/control-plane/api/management-api/contract-agreement-api/src/main/java/org/eclipse/edc/connector/controlplane/api/management/contractagreement/BaseContractAgreementApiController.java

@@ -16,13 +16,6 @@
 
 import jakarta.json.JsonArray;
 import jakarta.json.JsonObject;
-import jakarta.ws.rs.Consumes;
-import jakarta.ws.rs.GET;
-import jakarta.ws.rs.POST;
-import jakarta.ws.rs.Path;
-import jakarta.ws.rs.PathParam;
-import jakarta.ws.rs.Produces;
-import jakarta.ws.rs.core.MediaType;
 import org.eclipse.edc.connector.controlplane.contract.spi.types.agreement.ContractAgreement;
 import org.eclipse.edc.connector.controlplane.contract.spi.types.offer.ContractDefinition;
 import org.eclipse.edc.connector.controlplane.services.spi.contractagreement.ContractAgreementService;
@@ -42,8 +35,6 @@
 import static org.eclipse.edc.spi.query.QuerySpec.EDC_QUERY_SPEC_TYPE;
 import static org.eclipse.edc.web.spi.exception.ServiceResultHandler.exceptionMapper;
 
-@Consumes({ MediaType.APPLICATION_JSON })
-@Produces({ MediaType.APPLICATION_JSON })
 public abstract class BaseContractAgreementApiController {
  protected final Monitor monitor;
  private final ContractAgreementService service;
@@ -58,8 +49,6 @@ public BaseContractAgreementApiController(ContractAgreementService service, Type
  this.validatorRegistry = validatorRegistry;
  }
 
- @POST
- @Path("/request")
  public JsonArray queryAgreements(JsonObject querySpecJson) {
  QuerySpec querySpec;
  if (querySpecJson == null) {
@@ -79,19 +68,15 @@ public JsonArray queryAgreements(JsonObject querySpecJson) {
  .collect(toJsonArray());
  }
 
- @GET
- @Path("{id}")
- public JsonObject getAgreementById(@PathParam("id") String id) {
+ public JsonObject getAgreementById(String id) {
  return Optional.of(id)
  .map(service::findById)
  .map(it -> transformerRegistry.transform(it, JsonObject.class)
  .orElseThrow(failure -> new EdcException(failure.getFailureDetail())))
  .orElseThrow(() -> new ObjectNotFoundException(ContractAgreement.class, id));
  }
 
- @GET
- @Path("{id}/negotiation")
- public JsonObject getNegotiationByAgreementId(@PathParam("id") String id) {
+ public JsonObject getNegotiationByAgreementId(String id) {
  return Optional.of(id)
  .map(service::findNegotiation)
  .map(it -> transformerRegistry.transform(it, JsonObject.class)