Simplify maintainance of OpenAPI contract test

[dsmf]

As developer ,
I want easy maintenance of IrsApplicationTests#generatedOpenApiMatchesContract ,
so that maintenance for API changes are less time consuming and less error prone.

Hints / Details

• at the moment the diff is not very helpful:
  • order changes, therefore 1:1 diff not possible, the current workaround via maps that are compared recursively makes it hard to locate the changes in the sources
  • error messages are hard to read
  • therefore it takes a lot of time to do the adjustments when API changes
• maybe OpenaAPI-Diff could help here: https://github.com/OpenAPITools/openapi-diff

extract from documentation:

public class Main {
    public static final String OPENAPI_DOC1 = "petstore_v3_1.json";
    public static final String OPENAPI_DOC2 = "petstore_v2_2.yaml";
        
    public static void main(String[] args) {
        ChangedOpenApi diff = OpenApiCompare.fromLocations(OPENAPI_DOC1, OPENAPI_DOC2);

        //...
    }
}

• furthermore there seems to be a github actions based alternative: https://github.com/Tufin/oasdiff

Acceptance Criteria

• investigate whether OpenAPI diff would improve the current situation
• easier to see the difference on changes
• OpenAPI is compared to the contract in a semantic way ignoring different order

Out of Scope

• ...

[dsmf]

The following patch can be used as a start:

Subject: [PATCH] experiment #581 "Simplify maintainance of OpenAPI contract test"

- not complete yet
- at the moment just uses MarkdownRender to write diff to a markdown file
---
Index: irs-api/src/test/java/org/eclipse/tractusx/irs/IrsApplicationTests.java
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/irs-api/src/test/java/org/eclipse/tractusx/irs/IrsApplicationTests.java b/irs-api/src/test/java/org/eclipse/tractusx/irs/IrsApplicationTests.java
--- a/irs-api/src/test/java/org/eclipse/tractusx/irs/IrsApplicationTests.java	(revision f6c981272c5308f06b350e97e66a94177bb02075)
+++ b/irs-api/src/test/java/org/eclipse/tractusx/irs/IrsApplicationTests.java	(date 1714670500278)
@@ -25,6 +25,8 @@
 
 import static org.assertj.core.api.Assertions.assertThat;
 
+import java.io.FileWriter;
+import java.io.IOException;
 import java.io.InputStream;
 import java.nio.file.Files;
 import java.nio.file.Path;
@@ -47,6 +49,9 @@
 import org.eclipse.tractusx.irs.connector.job.JobStore;
 import org.eclipse.tractusx.irs.connector.job.ResponseStatus;
 import org.junit.jupiter.api.Test;
+import org.openapitools.openapidiff.core.OpenApiCompare;
+import org.openapitools.openapidiff.core.model.ChangedOpenApi;
+import org.openapitools.openapidiff.core.output.MarkdownRender;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.boot.test.context.SpringBootTest;
 import org.springframework.boot.test.context.SpringBootTest.WebEnvironment;
@@ -82,12 +87,23 @@
 
         final String generatedYaml = this.restTemplate.getForObject("http://localhost:" + port + "/api/api-docs.yaml",
                 String.class);
-        final InputStream definedYaml = Files.newInputStream(Path.of("../docs/src/api/irs-api.yaml"));
+        final Path definedYamlPath = Path.of("../docs/src/api/irs-api.yaml");
+        final InputStream definedYaml = Files.newInputStream(definedYamlPath);
 
         final ObjectMapper mapper = new ObjectMapper(new YAMLFactory());
         final Map<String, Object> definedYamlMap = mapper.readerForMapOf(Object.class).readValue(definedYaml);
         final Map<String, Object> generatedYamlMap = mapper.readerForMapOf(Object.class).readValue(generatedYaml);
 
+        final String definedYamlStr = Files.readString(definedYamlPath);
+        final ChangedOpenApi diff = OpenApiCompare.fromContents(generatedYaml, definedYamlStr);
+
+        final String render = new MarkdownRender().render(diff);
+        try (final FileWriter fw = new FileWriter("testDiff.md")) {
+            fw.write(render);
+        } catch (IOException e) {
+            e.printStackTrace();
+        }
+
         // 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)
Index: irs-api/pom.xml
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/irs-api/pom.xml b/irs-api/pom.xml
--- a/irs-api/pom.xml	(revision f6c981272c5308f06b350e97e66a94177bb02075)
+++ b/irs-api/pom.xml	(date 1714666116281)
@@ -214,6 +214,13 @@
             <artifactId>commons-validator</artifactId>
             <version>${commons-validator.version}</version>
         </dependency>
+        <dependency>
+            <groupId>org.openapitools.openapidiff</groupId>
+            <artifactId>openapi-diff-core</artifactId>
+            <version>2.0.1</version>
+            <scope>test</scope>
+        </dependency>
+
     </dependencies>
 
     <build>

[mkanal]

wontdo