feat: add agreement endpoints schema examples

extensions/common/api/management-api-configuration/build.gradle.kts

@@ -24,7 +24,10 @@ dependencies {
     implementation(project(":core:common:transform-core"))
     implementation(project(":extensions:common:api:api-core"))
 
+    implementation(libs.swagger.annotations.jakarta)
+
     testImplementation(project(":core:common:junit"))
+    testImplementation(project(":extensions:common:json-ld"))
 }
 
 edcBuild {

extensions/common/api/management-api-configuration/src/main/java/org/eclipse/edc/connector/api/management/configuration/ManagementApiConfigurationExtension.java

@@ -14,8 +14,10 @@
 
 package org.eclipse.edc.connector.api.management.configuration;
 
+import jakarta.json.Json;
 import org.eclipse.edc.api.auth.spi.AuthenticationRequestFilter;
 import org.eclipse.edc.api.auth.spi.AuthenticationService;
+import org.eclipse.edc.connector.api.management.configuration.transform.JsonObjectFromContractAgreementTransformer;
 import org.eclipse.edc.connector.api.management.configuration.transform.ManagementApiTypeTransformerRegistry;
 import org.eclipse.edc.connector.api.management.configuration.transform.ManagementApiTypeTransformerRegistryImpl;
 import org.eclipse.edc.jsonld.spi.JsonLd;
@@ -34,6 +36,8 @@
 import org.eclipse.edc.web.spi.configuration.WebServiceConfigurer;
 import org.eclipse.edc.web.spi.configuration.WebServiceSettings;
 
+import java.util.Map;
+
 import static org.eclipse.edc.spi.CoreConstants.JSON_LD;
 
 /**
@@ -101,6 +105,10 @@ public void initialize(ServiceExtensionContext context) {
 
     @Provider
     public ManagementApiTypeTransformerRegistry managementApiTypeTransformerRegistry() {
-        return new ManagementApiTypeTransformerRegistryImpl(this.transformerRegistry);
+        var factory = Json.createBuilderFactory(Map.of());
+
+        var registry = new ManagementApiTypeTransformerRegistryImpl(this.transformerRegistry);
+        registry.register(new JsonObjectFromContractAgreementTransformer(factory));
+        return registry;
     }
 }

extensions/common/api/management-api-configuration/src/main/java/org/eclipse/edc/connector/api/management/configuration/ManagementApiSchema.java

@@ -0,0 +1,63 @@
+/*
+ *  Copyright (c) 2023 Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+ *
+ *  This program and the accompanying materials are made available under the
+ *  terms of the Apache License, Version 2.0 which is available at
+ *  https://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  SPDX-License-Identifier: Apache-2.0
+ *
+ *  Contributors:
+ *       Bayerische Motoren Werke Aktiengesellschaft (BMW AG) - initial API and implementation
+ *
+ */
+
+package org.eclipse.edc.connector.api.management.configuration;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import org.eclipse.edc.connector.contract.spi.types.agreement.ContractAgreement;
+
+import static org.eclipse.edc.jsonld.spi.JsonLdKeywords.ID;
+import static org.eclipse.edc.jsonld.spi.JsonLdKeywords.TYPE;
+
+/**
+ * Schema records that are shared between multiple management modules
+ */
+public interface ManagementApiSchema {
+
+    @Schema(example = ContractAgreementSchema.CONTRACT_AGREEMENT_EXAMPLE)
+    record ContractAgreementSchema(
+            @Schema(name = TYPE, example = ContractAgreement.CONTRACT_AGREEMENT_TYPE)
+            String ldType,
+            @Schema(name = ID)
+            String id,
+            String providerId,
+            String consumerId,
+            long contractSigningDate,
+            String assetId,
+            @Schema(description = "ODRL policy")
+            Object policy
+    ) {
+        public static final String CONTRACT_AGREEMENT_EXAMPLE = """
+                {
+                    "@context": { "edc": "https://w3id.org/edc/v0.0.1/ns/" },
+                    "@type": "https://w3id.org/edc/v0.0.1/ns/ContractAgreement",
+                    "@id": "negotiation-id",
+                    "providerId": "provider-id",
+                    "consumerId": "consumer-id",
+                    "assetId": "asset-id",
+                    "contractSigningDate": 1688465655,
+                    "policy": {
+                        "@context": "http://www.w3.org/ns/odrl.jsonld",
+                        "@type": "Set",
+                        "@id": "offer-id",
+                        "permission": [{
+                            "target": "asset-id",
+                            "action": "display"
+                        }]
+                    }
+                }
+                """;
+    }
+
+}

extensions/control-plane/api/management-api/contract-negotiation-api/src/main/java/org/eclipse/edc/connector/api/management/contractnegotiation/transform/JsonObjectFromContractAgreementTransformer.java → extensions/common/api/management-api-configuration/src/main/java/org/eclipse/edc/connector/api/management/configuration/transform/JsonObjectFromContractAgreementTransformer.java

@@ -12,7 +12,7 @@
  *
  */
 
-package org.eclipse.edc.connector.api.management.contractnegotiation.transform;
+package org.eclipse.edc.connector.api.management.configuration.transform;
 
 import jakarta.json.JsonBuilderFactory;
 import jakarta.json.JsonObject;
@@ -40,15 +40,15 @@ public JsonObjectFromContractAgreementTransformer(JsonBuilderFactory jsonFactory
     }
 
     @Override
-    public @Nullable JsonObject transform(@NotNull ContractAgreement dto, @NotNull TransformerContext context) {
+    public @Nullable JsonObject transform(@NotNull ContractAgreement agreement, @NotNull TransformerContext context) {
         return jsonFactory.createObjectBuilder()
                 .add(TYPE, CONTRACT_AGREEMENT_TYPE)
-                .add(ID, dto.getId())
-                .add(CONTRACT_AGREEMENT_ASSET_ID, dto.getAssetId())
-                .add(CONTRACT_AGREEMENT_POLICY, context.transform(dto.getPolicy(), JsonObject.class))
-                .add(CONTRACT_AGREEMENT_SIGNING_DATE, dto.getContractSigningDate())
-                .add(CONTRACT_AGREEMENT_CONSUMER_ID, dto.getConsumerId())
-                .add(CONTRACT_AGREEMENT_PROVIDER_ID, dto.getProviderId())
+                .add(ID, agreement.getId())
+                .add(CONTRACT_AGREEMENT_ASSET_ID, agreement.getAssetId())
+                .add(CONTRACT_AGREEMENT_POLICY, context.transform(agreement.getPolicy(), JsonObject.class))
+                .add(CONTRACT_AGREEMENT_SIGNING_DATE, agreement.getContractSigningDate())
+                .add(CONTRACT_AGREEMENT_CONSUMER_ID, agreement.getConsumerId())
+                .add(CONTRACT_AGREEMENT_PROVIDER_ID, agreement.getProviderId())
                 .build();
     }
 }

extensions/common/api/management-api-configuration/src/test/java/org/eclipse/edc/connector/api/management/configuration/ManagementApiSchemaTest.java

@@ -0,0 +1,60 @@
+/*
+ *  Copyright (c) 2023 Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+ *
+ *  This program and the accompanying materials are made available under the
+ *  terms of the Apache License, Version 2.0 which is available at
+ *  https://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  SPDX-License-Identifier: Apache-2.0
+ *
+ *  Contributors:
+ *       Bayerische Motoren Werke Aktiengesellschaft (BMW AG) - initial API and implementation
+ *
+ */
+
+package org.eclipse.edc.connector.api.management.configuration;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import jakarta.json.JsonObject;
+import org.eclipse.edc.jsonld.JsonLdExtension;
+import org.eclipse.edc.jsonld.spi.JsonLd;
+import org.eclipse.edc.jsonld.util.JacksonJsonLd;
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.AssertionsForClassTypes.assertThat;
+import static org.eclipse.edc.connector.api.management.configuration.ManagementApiSchema.ContractAgreementSchema.CONTRACT_AGREEMENT_EXAMPLE;
+import static org.eclipse.edc.connector.contract.spi.types.agreement.ContractAgreement.CONTRACT_AGREEMENT_ASSET_ID;
+import static org.eclipse.edc.connector.contract.spi.types.agreement.ContractAgreement.CONTRACT_AGREEMENT_CONSUMER_ID;
+import static org.eclipse.edc.connector.contract.spi.types.agreement.ContractAgreement.CONTRACT_AGREEMENT_POLICY;
+import static org.eclipse.edc.connector.contract.spi.types.agreement.ContractAgreement.CONTRACT_AGREEMENT_PROVIDER_ID;
+import static org.eclipse.edc.connector.contract.spi.types.agreement.ContractAgreement.CONTRACT_AGREEMENT_SIGNING_DATE;
+import static org.eclipse.edc.connector.contract.spi.types.agreement.ContractAgreement.CONTRACT_AGREEMENT_TYPE;
+import static org.eclipse.edc.jsonld.spi.JsonLdKeywords.ID;
+import static org.eclipse.edc.jsonld.spi.JsonLdKeywords.TYPE;
+import static org.eclipse.edc.jsonld.spi.JsonLdKeywords.VALUE;
+import static org.eclipse.edc.junit.assertions.AbstractResultAssert.assertThat;
+import static org.eclipse.edc.junit.extensions.TestServiceExtensionContext.testServiceExtensionContext;
+
+class ManagementApiSchemaTest {
+
+    private final ObjectMapper objectMapper = JacksonJsonLd.createObjectMapper();
+    private final JsonLd jsonLd = new JsonLdExtension().createJsonLdService(testServiceExtensionContext());
+
+    @Test
+    void contractAgreementExample() throws JsonProcessingException {
+        var jsonObject = objectMapper.readValue(CONTRACT_AGREEMENT_EXAMPLE, JsonObject.class);
+        var expanded = jsonLd.expand(jsonObject);
+
+        assertThat(expanded).isSucceeded().satisfies(content -> {
+            assertThat(content.getString(ID)).isNotBlank();
+            assertThat(content.getJsonArray(TYPE).getString(0)).isEqualTo(CONTRACT_AGREEMENT_TYPE);
+            assertThat(content.getJsonArray(CONTRACT_AGREEMENT_ASSET_ID).getJsonObject(0).getString(VALUE)).isNotBlank();
+            assertThat(content.getJsonArray(CONTRACT_AGREEMENT_PROVIDER_ID).getJsonObject(0).getString(VALUE)).isNotBlank();
+            assertThat(content.getJsonArray(CONTRACT_AGREEMENT_CONSUMER_ID).getJsonObject(0).getString(VALUE)).isNotBlank();
+            assertThat(content.getJsonArray(CONTRACT_AGREEMENT_SIGNING_DATE).getJsonObject(0).getJsonNumber(VALUE).longValue()).isGreaterThan(0);
+            assertThat(content.getJsonArray(CONTRACT_AGREEMENT_POLICY).getJsonObject(0)).isNotNull();
+        });
+    }
+
+}

extensions/control-plane/api/management-api/contract-negotiation-api/src/test/java/org/eclipse/edc/connector/api/management/contractnegotiation/transform/JsonObjectFromContractAgreementTransformerTest.java → extensions/common/api/management-api-configuration/src/test/java/org/eclipse/edc/connector/api/management/configuration/transform/JsonObjectFromContractAgreementTransformerTest.java

@@ -12,7 +12,7 @@
  *
  */
 
-package org.eclipse.edc.connector.api.management.contractnegotiation.transform;
+package org.eclipse.edc.connector.api.management.configuration.transform;
 
 import jakarta.json.Json;
 import jakarta.json.JsonObject;

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

@@ -24,19 +24,19 @@
 import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.json.JsonArray;
 import jakarta.json.JsonObject;
-import org.eclipse.edc.api.model.QuerySpecDto;
-import org.eclipse.edc.connector.api.management.contractagreement.model.ContractAgreementDto;
+import org.eclipse.edc.api.model.ApiCoreSchema;
+import org.eclipse.edc.connector.api.management.configuration.ManagementApiSchema;
 import org.eclipse.edc.web.spi.ApiErrorDetail;
 
 @OpenAPIDefinition
 @Tag(name = "Contract Agreement")
 public interface ContractAgreementApi {
 
     @Operation(description = "Gets all contract agreements according to a particular query",
-            requestBody = @RequestBody(content = @Content(schema = @Schema(implementation = QuerySpecDto.class))),
+            requestBody = @RequestBody(content = @Content(schema = @Schema(implementation = ApiCoreSchema.QuerySpecSchema.class))),
             responses = {
                     @ApiResponse(responseCode = "200", description = "The contract agreements matching the query",
-                            content = @Content(array = @ArraySchema(schema = @Schema(implementation = ContractAgreementDto.class)))),
+                            content = @Content(array = @ArraySchema(schema = @Schema(implementation = ManagementApiSchema.ContractAgreementSchema.class)))),
                     @ApiResponse(responseCode = "400", description = "Request body was malformed",
                             content = @Content(array = @ArraySchema(schema = @Schema(implementation = ApiErrorDetail.class))))
             }
@@ -46,7 +46,7 @@ public interface ContractAgreementApi {
     @Operation(description = "Gets an contract agreement with the given ID",
             responses = {
                     @ApiResponse(responseCode = "200", description = "The contract agreement",
-                            content = @Content(schema = @Schema(implementation = ContractAgreementDto.class))),
+                            content = @Content(schema = @Schema(implementation = ManagementApiSchema.ContractAgreementSchema.class))),
                     @ApiResponse(responseCode = "400", description = "Request was malformed, e.g. id was null",
                             content = @Content(array = @ArraySchema(schema = @Schema(implementation = ApiErrorDetail.class)))),
                     @ApiResponse(responseCode = "404", description = "An contract agreement with the given ID does not exist",

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

@@ -23,7 +23,6 @@
 import jakarta.ws.rs.Produces;
 import jakarta.ws.rs.core.MediaType;
 import org.eclipse.edc.api.model.QuerySpecDto;
-import org.eclipse.edc.connector.api.management.contractagreement.model.ContractAgreementDto;
 import org.eclipse.edc.connector.contract.spi.types.agreement.ContractAgreement;
 import org.eclipse.edc.connector.contract.spi.types.offer.ContractDefinition;
 import org.eclipse.edc.connector.spi.contractagreement.ContractAgreementService;
@@ -76,8 +75,7 @@ public JsonArray queryAllAgreements(JsonObject querySpecDto) {
 
         try (var stream = service.query(querySpec).orElseThrow(exceptionMapper(ContractDefinition.class, null))) {
             return stream
-                    .map(it -> transformerRegistry.transform(it, ContractAgreementDto.class)
-                            .compose(dto -> transformerRegistry.transform(dto, JsonObject.class)))
+                    .map(it -> transformerRegistry.transform(it, JsonObject.class))
                     .peek(r -> r.onFailure(f -> monitor.warning(f.getFailureDetail())))
                     .filter(Result::succeeded)
                     .map(Result::getContent)
@@ -91,8 +89,7 @@ public JsonArray queryAllAgreements(JsonObject querySpecDto) {
     public JsonObject getAgreementById(@PathParam("id") String id) {
         return Optional.of(id)
                 .map(service::findById)
-                .map(it -> transformerRegistry.transform(it, ContractAgreementDto.class)
-                        .compose(dto -> transformerRegistry.transform(dto, JsonObject.class))
+                .map(it -> transformerRegistry.transform(it, JsonObject.class)
                         .orElseThrow(failure -> new EdcException(failure.getFailureDetail())))
                 .orElseThrow(() -> new ObjectNotFoundException(ContractAgreement.class, id));
     }

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

@@ -15,11 +15,8 @@
 
 package org.eclipse.edc.connector.api.management.contractagreement;
 
-import jakarta.json.Json;
 import org.eclipse.edc.connector.api.management.configuration.ManagementApiConfiguration;
 import org.eclipse.edc.connector.api.management.configuration.transform.ManagementApiTypeTransformerRegistry;
-import org.eclipse.edc.connector.api.management.contractagreement.transform.ContractAgreementToContractAgreementDtoTransformer;
-import org.eclipse.edc.connector.api.management.contractagreement.transform.JsonObjectFromContractAgreementDtoTransformer;
 import org.eclipse.edc.connector.spi.contractagreement.ContractAgreementService;
 import org.eclipse.edc.runtime.metamodel.annotation.Extension;
 import org.eclipse.edc.runtime.metamodel.annotation.Inject;
@@ -28,8 +25,6 @@
 import org.eclipse.edc.validator.spi.JsonObjectValidatorRegistry;
 import org.eclipse.edc.web.spi.WebService;
 
-import java.util.Map;
-
 @Extension(value = ContractAgreementApiExtension.NAME)
 public class ContractAgreementApiExtension implements ServiceExtension {
 
@@ -56,8 +51,6 @@ public String name() {
 
     @Override
     public void initialize(ServiceExtensionContext context) {
-        transformerRegistry.register(new ContractAgreementToContractAgreementDtoTransformer());
-        transformerRegistry.register(new JsonObjectFromContractAgreementDtoTransformer(Json.createBuilderFactory(Map.of())));
         var monitor = context.getMonitor();
 
         var controller = new ContractAgreementApiController(service, transformerRegistry, monitor, validatorRegistry);