Merge pull request #813 from catenax-ng/feat/#241-refactor-aopen-api-…

…docs-to-not-contain-duplicates

Feat/#241 refactor open api docs to not contain duplicates

docs/src/api/irs-api.yaml

@@ -257,9 +257,6 @@ paths:
         "200":
           content:
             application/json:
-              examples:
-                complete:
-                  $ref: '#/components/examples/complete-job-list-processing-state'
               schema:
                 $ref: '#/components/schemas/PageResult'
           description: Paginated list of jobs with state and execution times for requested
@@ -1617,6 +1614,16 @@ components:
             - PROCESSING
             - PARTIAL
             - ERROR
+      example:
+        batchChecksum: 1
+        batches:
+          - batchId: f253718e-a270-4367-901b-9d50d9bd8462
+            batchNumber: 1
+            batchProcessingState: PARTIAL
+            batchUrl: https://../irs/orders/f253718e-a270-4367-901b-9d50d9bd8462/batches/f253718e-a270-4367-901b-9d50d9bd8462
+            jobsInBatchChecksum: 1
+        orderId: f253718e-a270-4367-901b-9d50d9bd8462
+        state: COMPLETED
     BatchResponse:
       type: object
       additionalProperties: false
@@ -1673,6 +1680,21 @@ components:
           type: integer
           format: int32
           description: Total amount of jobs inside the order.
+      example:
+        batchId: f253718e-a270-4367-901b-9d50d9bd8462
+        batchNumber: 1
+        batchProcessingState: COMPLETED
+        batchTotal: 1
+        completedOn: '2022-02-03T14:48:54.709Z'
+        jobs:
+          - completedOn: '2022-02-03T14:48:54.709Z'
+            id: 6c311d29-5753-46d4-b32c-19b918ea93b0
+            startedOn: '2022-02-03T14:48:54.709Z'
+            state: COMPLETED
+        jobsInBatchChecksum: 1
+        orderId: f253718e-a270-4367-901b-9d50d9bd8462
+        startedOn: '2022-02-03T14:48:54.709Z'
+        totalJobs: 1
     Bpn:
       type: object
       additionalProperties: false
@@ -2066,6 +2088,120 @@ components:
       type: object
       additionalProperties: false
       description: Container for a job with item graph.
+      example:
+        bpns:
+          - manufacturerId: BPNL00000003AAXX
+            manufacturerName: AB CD
+        job:
+          completedOn: '2022-02-03T14:48:54.709Z'
+          createdOn: '2022-02-03T14:48:54.709Z'
+          exception:
+            errorDetail: Timeout while requesting Digital Registry
+            exception: IrsTimeoutException
+            exceptionDate: '2022-02-03T14:48:54.709Z'
+          globalAssetId: urn:uuid:6c311d29-5753-46d4-b32c-19b918ea93b0
+          id: e5347c88-a921-11ec-b909-0242ac120002
+          lastModifiedOn: '2022-02-03T14:48:54.709Z'
+          parameter:
+            aspects:
+              - SerialPart
+              - AddressAspect
+            auditContractNegotiation: false
+            bomLifecycle: asBuilt
+            collectAspects: false
+            depth: 1
+            direction: downward
+            lookupBPNs: false
+          startedOn: '2022-02-03T14:48:54.709Z'
+          state: COMPLETED
+          summary:
+            asyncFetchedItems:
+              completed: 3
+              failed: 0
+              running: 0
+            bpnLookups:
+              completed: 3
+              failed: 0
+        relationships:
+          - catenaXId: urn:uuid:d9bec1c6-e47c-4d18-ba41-0a5fe8b7f447
+            linkedItem:
+              assembledOn: '2022-02-03T14:48:54.709Z'
+              childCatenaXId: urn:uuid:a45a2246-f6e1-42da-b47d-5c3b58ed62e9
+              hasAlternatives: false
+              lastModifiedOn: '2022-02-03T14:48:54.709Z'
+              lifecycleContext: asBuilt
+              quantity:
+                measurementUnit:
+                  datatypeURI: urn:bamm:io.openmanufacturing:meta-model:1.0.0#piece
+                  lexicalValue: piece
+                quantityNumber: 1
+        shells:
+          - contractAgreementId: f253718e-a270-4367-901b-9d50d9bd8462
+            payload:
+              description:
+                - language: en
+                  text: The shell for a vehicle
+              globalAssetId: urn:uuid:a45a2246-f6e1-42da-b47d-5c3b58ed62e9
+              id: urn:uuid:882fc530-b69b-4707-95f6-5dbc5e9baaa8
+              idShort: future concept x
+              specificAssetIds:
+                - name: engineserialid
+                  value: '12309481209312'
+              submodelDescriptors:
+                - description:
+                    - language: en
+                      text: Provides base vehicle information
+                  endpoints:
+                    - interface: HTTP
+                      protocolInformation:
+                        endpointProtocol: HTTPS
+                        endpointProtocolVersion:
+                          - '1.0'
+                        href: https://catena-x.net/vehicle/basedetails/
+                        subprotocol: DSP
+                        subprotocolBody: id=urn:uuid:c8159379-4613-48b8-ad52-6baed7afe923;dspEndpoint=https://irs-provider-controlplane3.dev.demo.catena-x.net
+                        subprotocolBodyEncoding: plain
+                  id: urn:uuid:5d25a897-6571-4800-b98c-a3352fbf996d
+                  idShort: SingleLevelBomAsPlanned
+                  semanticId:
+                    keys:
+                      - type: ExternalReference
+                        value: urn:bamm:io.catenax.single_level_bom_as_planned:2.0.0#SingleLevelBomAsPlanned
+                    type: ModelReference
+                - description:
+                    - language: en
+                      text: Provides base vehicle information
+                  endpoints:
+                    - interface: HTTP
+                      protocolInformation:
+                        endpointProtocol: HTTPS
+                        endpointProtocolVersion:
+                          - '1.0'
+                        href: https://catena-x.net/vehicle/partdetails/
+                        subprotocol: DSP
+                        subprotocolBody: id=urn:uuid:c8159379-4613-48b8-ad52-6baed7afe923;dspEndpoint=https://irs-provider-controlplane3.dev.demo.catena-x.net
+                        subprotocolBodyEncoding: plain
+                  id: urn:uuid:dae4d249-6d66-4818-b576-bf52f3b9ae90
+                  idShort: vehicle part details
+                  semanticId:
+                    keys:
+                      - type: Submodel
+                        value: urn:bamm:com.catenax.vehicle:0.1.1#PartDetails
+                    type: ModelReference
+        submodels:
+          - aspectType: supply_chain_impacted
+            contractAgreementId: f253718e-a270-4367-901b-9d50d9bd8462
+            identification: urn:uuid:fc784d2a-5506-4e61-8e34-21600f8cdeff
+            payload:
+              supplyChainImpacted: 'YES'
+        tombstones:
+          - catenaXId: urn:uuid:6c311d29-5753-46d4-b32c-19b918ea93b0
+            endpointURL: https://catena-x.net/vehicle/partdetails/
+            processingError:
+              errorDetail: Details to reason of failure
+              lastAttempt: '2022-02-03T14:48:54.709Z'
+              processStep: SchemaValidation
+              retryCounter: 0
       properties:
         bpns:
           type: array
@@ -2216,6 +2352,16 @@ components:
     PageResult:
       type: object
       additionalProperties: false
+      example:
+        pageCount: 0
+        pageNumber: 6
+        pageSize: 1
+        content:
+          - completedOn: test
+            id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
+            startedOn: 2000-01-23T04:56:07.000+00:00
+            state: UNSAVED
+        totalElements: 5
       properties:
         content:
           type: array
@@ -2269,6 +2415,23 @@ components:
         constraint:
           $ref: '#/components/schemas/Constraints'
     Policy:
+      example:
+        createdOn: '2024-03-08T15:19:41.006Z'
+        permissions:
+          - action: USE
+            constraint:
+              and:
+                - leftOperand: string
+                  odrl:rightOperand: string
+                  operator:
+                    "@id": odrl:eq
+              or:
+                - leftOperand: string
+                  odrl:rightOperand: string
+                  operator:
+                    "@id": odrl:eq
+        policyId: f253718e-a270-4367-901b-9d50d9bd8462
+        validUntil: '2024-03-08T15:19:41.006Z'
       type: object
       additionalProperties: false
       properties:
@@ -2750,6 +2913,19 @@ components:
     AspectModels:
       type: object
       additionalProperties: false
+      example:
+        lastUpdated: 2023-02-13T08:18:11.990659500Z
+        models:
+          - urn: urn:bamm:io.catenax.single_level_bom_as_built:1.0.0#SingleLevelBomAsBuilt
+            name: SingleLevelBomAsBuilt
+            type: BAMM
+            version: 1.0.0
+            status: RELEASED
+          - urn: urn:bamm:io.catenax.serial_part:1.0.0#SerialPart
+            name: SerialPart
+            type: BAMM
+            version: 1.0.0
+            status: RELEASED
       properties:
         lastUpdated:
           type: string

irs-api/src/main/java/org/eclipse/tractusx/irs/controllers/IrsController.java

@@ -240,9 +240,7 @@ public Job cancelJobByJobId(
     @ApiResponses(value = { @ApiResponse(responseCode = "200",
                                          description = "Paginated list of jobs with state and execution times for requested job states.",
                                          content = { @Content(mediaType = APPLICATION_JSON_VALUE,
-                                                              schema = @Schema(implementation = PageResult.class),
-                                                              examples = @ExampleObject(name = "complete",
-                                                                                        ref = "#/components/examples/complete-job-list-processing-state"))
+                                                              schema = @Schema(implementation = PageResult.class))
                                          }),
                             @ApiResponse(responseCode = "400",
                                          description = "Return jobs for requested job states failed.",

irs-api/src/main/java/org/eclipse/tractusx/irs/semanticshub/AspectModels.java

@@ -25,13 +25,16 @@
 
 import java.util.List;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Builder;
 
 /**
  * @param models list of semantic models
  * @param lastUpdated timestamp of latest update
  */
 @Builder
+@Schema(example = AspectModels.EXAMPLE)
 public record AspectModels(List<AspectModel> models, String lastUpdated) {
-
+    public static final String EXAMPLE = "{\"lastUpdated\"=\"2023-02-13T08:18:11.990659500Z\", \"models\"=[{\"name\"=\"SingleLevelBomAsBuilt\", \"status\"=\"RELEASED\", \"type\"=\"BAMM\", \"urn\"=\"urn:bamm:io.catenax.single_level_bom_as_built:1.0.0#SingleLevelBomAsBuilt\", \"version\"=\"1.0.0\"},\n"
+            + "    {\"name\"=\"SerialPart\", \"status\"=\"RELEASED\", \"type\"=\"BAMM\", \"urn\"=\"urn:bamm:io.catenax.serial_part:1.0.0#SerialPart\", \"version\"=\"1.0.0\"}]}";
 }

irs-api/src/test/java/org/eclipse/tractusx/irs/IrsApplicationTests.java

@@ -84,7 +84,16 @@ void generatedOpenApiMatchesContract() throws Exception {
         final Map<String, Object> fixedYamlMap = mapper.readerForMapOf(Object.class).readValue(fixedYaml);
         final Map<String, Object> generatedYamlMap = mapper.readerForMapOf(Object.class).readValue(generatedYaml);
 
-        assertThat(generatedYamlMap).isEqualTo(fixedYamlMap);
+        // To correctly display both documentations examples - manual and generated by annotations -
+        // we need to remove verification for some "examples", otherwise one or another won't display correctly
+        assertThat(generatedYamlMap).usingRecursiveComparison()
+                                    .ignoringFields("components.schemas.PageResult.example")
+                                    .ignoringFields("components.schemas.AspectModels.example")
+                                    .ignoringFields("components.schemas.BatchOrderResponse.example")
+                                    .ignoringFields("components.schemas.Jobs.example")
+                                    .ignoringFields("components.schemas.Policy")
+                                    .ignoringFields("components.schemas.BatchResponse.example")
+                                    .isEqualTo(fixedYamlMap);
     }
 
     @Test

irs-api/src/test/java/org/eclipse/tractusx/irs/connector/job/InMemoryJobStoreTest.java

@@ -37,6 +37,7 @@
 import org.assertj.core.api.SoftAssertions;
 import org.eclipse.tractusx.irs.component.Job;
 import org.eclipse.tractusx.irs.component.JobErrorDetails;
+import org.eclipse.tractusx.irs.component.Jobs;
 import org.eclipse.tractusx.irs.component.enums.JobState;
 import org.eclipse.tractusx.irs.util.TestMother;
 import org.junit.jupiter.api.Test;

irs-models/src/main/java/org/eclipse/tractusx/irs/component/BatchOrderResponse.java

@@ -37,13 +37,15 @@
 /**
  * BatchOrderAck Payload Response
  */
-@Schema(description = "BatchOrderAck Payload Response.")
+@Schema(description = "BatchOrderAck Payload Response.", example = BatchOrderResponse.EXAMPLE)
 @Value
 @Builder
 @AllArgsConstructor
 @Jacksonized
 public class BatchOrderResponse {
 
+    public static final String EXAMPLE = "{\"batchChecksum\"=1, \"batches\"=[{\"batchId\"=\"f253718e-a270-4367-901b-9d50d9bd8462\", \"batchNumber\"=1, \"batchProcessingState\"=\"PARTIAL\", \"batchUrl\"=\"https://../irs/orders/f253718e-a270-4367-901b-9d50d9bd8462/batches/f253718e-a270-4367-901b-9d50d9bd8462\", \"jobsInBatchChecksum\"=1}], \"orderId\"=\"f253718e-a270-4367-901b-9d50d9bd8462\", \"state\"=\"COMPLETED\"}";
+
     private static final int UUID_LENGTH = 36;
 
     @Schema(description = "Id of the order.", minLength = UUID_LENGTH,

irs-models/src/main/java/org/eclipse/tractusx/irs/component/BatchResponse.java

@@ -38,14 +38,15 @@
 /**
  * Batch model
  */
-@Schema(description = "Batch model.")
+@Schema(description = "Batch model.", example = BatchResponse.EXAMPLE)
 @Value
 @Builder
 @AllArgsConstructor
 @Jacksonized
 public class BatchResponse {
 
     private static final int UUID_LENGTH = 36;
+    public static final String EXAMPLE = "{\"batchId\"=\"f253718e-a270-4367-901b-9d50d9bd8462\", \"batchNumber\"=1, \"batchProcessingState\"=\"COMPLETED\", \"batchTotal\"=1, \"completedOn\"=\"2022-02-03T14:48:54.709Z\", \"jobs\"=[{\"completedOn\"=\"2022-02-03T14:48:54.709Z\", \"id\"=\"6c311d29-5753-46d4-b32c-19b918ea93b0\", \"startedOn\"=\"2022-02-03T14:48:54.709Z\", \"state\"=\"COMPLETED\"}], \"jobsInBatchChecksum\"=1, \"orderId\"=\"f253718e-a270-4367-901b-9d50d9bd8462\", \"startedOn\"=\"2022-02-03T14:48:54.709Z\", \"totalJobs\"=1}";
 
     @Schema(description = "Id of the order.", minLength = UUID_LENGTH,
             maxLength = UUID_LENGTH, implementation = UUID.class,

irs-models/src/main/java/org/eclipse/tractusx/irs/component/Jobs.java

@@ -37,7 +37,7 @@
 /**
  * List of Job and relationship to parts
  */
-@Schema(description = "Container for a job with item graph.")
+@Schema(description = "Container for a job with item graph.", example = Jobs.EXAMPLE)
 @Value
 @Builder(toBuilder = true)
 @AllArgsConstructor
@@ -67,4 +67,7 @@ public class Jobs {
     @Singular
     private Set<Bpn> bpns;
 
+    /* package */ static final String EXAMPLE = "{\"bpns\"=[{\"manufacturerId\"=\"BPNL00000003AAXX\", \"manufacturerName\"=\"AB CD\"}], \"job\"={\"completedOn\"=\"2022-02-03T14:48:54.709Z\", \"createdOn\"=\"2022-02-03T14:48:54.709Z\", \"exception\"={\"errorDetail\"=\"Timeout while requesting Digital Registry\", \"exception\"=\"IrsTimeoutException\", \"exceptionDate\"=\"2022-02-03T14:48:54.709Z\"}, \"globalAssetId\"=\"urn:uuid:6c311d29-5753-46d4-b32c-19b918ea93b0\", \"id\"=\"e5347c88-a921-11ec-b909-0242ac120002\", \"lastModifiedOn\"=\"2022-02-03T14:48:54.709Z\", \"parameter\"={\"aspects\"=[\"SerialPart\", \"AddressAspect\"], \"auditContractNegotiation\"=false, \"bomLifecycle\"=\"asBuilt\", \"collectAspects\"=false, \"depth\"=1, \"direction\"=\"downward\", \"lookupBPNs\"=false}, \"startedOn\"=\"2022-02-03T14:48:54.709Z\", \"state\"=\"COMPLETED\", \"summary\"={\"asyncFetchedItems\"={\"completed\"=3, \"failed\"=0, \"running\"=0}, \"bpnLookups\"={\"completed\"=3, \"failed\"=0}}}, \"relationships\"=[{\"catenaXId\"=\"urn:uuid:d9bec1c6-e47c-4d18-ba41-0a5fe8b7f447\", \"linkedItem\"={\"assembledOn\"=\"2022-02-03T14:48:54.709Z\", \"childCatenaXId\"=\"urn:uuid:a45a2246-f6e1-42da-b47d-5c3b58ed62e9\", \"hasAlternatives\"=false, \"lastModifiedOn\"=\"2022-02-03T14:48:54.709Z\", \"lifecycleContext\"=\"asBuilt\", \"quantity\"={\"measurementUnit\"={\"datatypeURI\"=\"urn:bamm:io.openmanufacturing:meta-model:1.0.0#piece\", \"lexicalValue\"=\"piece\"}, \"quantityNumber\"=1}}}], \"shells\"=[{\"contractAgreementId\"=\"f253718e-a270-4367-901b-9d50d9bd8462\", \"payload\"={\"description\"=[{\"language\"=\"en\", \"text\"=\"The shell for a vehicle\"}], \"globalAssetId\"=\"urn:uuid:a45a2246-f6e1-42da-b47d-5c3b58ed62e9\", \"id\"=\"urn:uuid:882fc530-b69b-4707-95f6-5dbc5e9baaa8\", \"idShort\"=\"future concept x\", \"specificAssetIds\"=[{\"name\"=\"engineserialid\", \"value\"=\"12309481209312\"}], \"submodelDescriptors\"=[{\"description\"=[{\"language\"=\"en\", \"text\"=\"Provides base vehicle information\"}], \"endpoints\"=[{\"interface\"=\"HTTP\", \"protocolInformation\"={\"endpointProtocol\"=\"HTTPS\", \"endpointProtocolVersion\"=[\"1.0\"], \"href\"=\"https://catena-x.net/vehicle/basedetails/\", \"subprotocol\"=\"DSP\", \"subprotocolBody\"=\"id=urn:uuid:c8159379-4613-48b8-ad52-6baed7afe923;dspEndpoint=https://irs-provider-controlplane3.dev.demo.catena-x.net\", \"subprotocolBodyEncoding\"=\"plain\"}}], \"id\"=\"urn:uuid:5d25a897-6571-4800-b98c-a3352fbf996d\", \"idShort\"=\"SingleLevelBomAsPlanned\", \"semanticId\"={\"keys\"=[{\"type\"=\"ExternalReference\", \"value\"=\"urn:bamm:io.catenax.single_level_bom_as_planned:2.0.0#SingleLevelBomAsPlanned\"}], \"type\"=\"ModelReference\"}},\n"
+            + "    {\"description\"=[{\"language\"=\"en\", \"text\"=\"Provides base vehicle information\"}], \"endpoints\"=[{\"interface\"=\"HTTP\", \"protocolInformation\"={\"endpointProtocol\"=\"HTTPS\", \"endpointProtocolVersion\"=[\"1.0\"], \"href\"=\"https://catena-x.net/vehicle/partdetails/\", \"subprotocol\"=\"DSP\", \"subprotocolBody\"=\"id=urn:uuid:c8159379-4613-48b8-ad52-6baed7afe923;dspEndpoint=https://irs-provider-controlplane3.dev.demo.catena-x.net\", \"subprotocolBodyEncoding\"=\"plain\"}}], \"id\"=\"urn:uuid:dae4d249-6d66-4818-b576-bf52f3b9ae90\", \"idShort\"=\"vehicle part details\", \"semanticId\"={\"keys\"=[{\"type\"=\"Submodel\", \"value\"=\"urn:bamm:com.catenax.vehicle:0.1.1#PartDetails\"}], \"type\"=\"ModelReference\"}}]}}], \"submodels\"=[{\"aspectType\"=\"supply_chain_impacted\", \"contractAgreementId\"=\"f253718e-a270-4367-901b-9d50d9bd8462\", \"identification\"=\"urn:uuid:fc784d2a-5506-4e61-8e34-21600f8cdeff\", \"payload\"={\"supplyChainImpacted\"=\"YES\"}}], \"tombstones\"=[{\"catenaXId\"=\"urn:uuid:6c311d29-5753-46d4-b32c-19b918ea93b0\", \"endpointURL\"=\"https://catena-x.net/vehicle/partdetails/\", \"processingError\"={\"errorDetail\"=\"Details to reason of failure\", \"lastAttempt\"=\"2022-02-03T14:48:54.709Z\", \"processStep\"=\"SchemaValidation\", \"retryCounter\"=0}}]}";
+
 }

irs-models/src/main/java/org/eclipse/tractusx/irs/component/PageResult.java

@@ -25,20 +25,26 @@
 
 import java.util.List;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import org.springframework.beans.support.PagedListHolder;
 
 /**
  * Paginated results for {@link JobStatusResult} content
  */
+@Schema(example = PageResult.EXAMPLE)
 public record PageResult(
+
         List<JobStatusResult> content,
         Integer pageNumber,
         Integer pageCount,
         Integer pageSize,
         Integer totalElements) {
 
+    public static final String EXAMPLE = "{\"content\"=[{\"completedOn\"=\"test\", \"id\"=\"046b6c7f-0b8a-43b9-b35d-6489e6daee91\", \"startedOn\"=\"2000-01-23T04:56:07.000+00:00\", \"state\"=\"UNSAVED\"}], \"pageCount\"=0, \"pageNumber\"=6, \"pageSize\"=1, \"totalElements\"=5}";
+
     public PageResult(final PagedListHolder<JobStatusResult> pagedListHolder) {
         this(pagedListHolder.getPageList(), pagedListHolder.getPage(), pagedListHolder.getPageCount(), pagedListHolder.getPageSize(), pagedListHolder.getNrOfElements());
     }
+
 }