Add builder for OpenAPIContract. #103

lukasjelonek · 2025-06-12T07:54:13Z

Will allow to add new fields to the contract setup without requiring to change or to add new factory methods.

Motivation:

Split the pull request #101 into two simpler request: one for the builder part, one for the additional media types. This pull request covers the first part.

Conformance:

You should have signed the Eclipse Contributor Agreement: Done
Please also make sure you adhere to the code style guidelines: https://github.com/vert-x3/wiki/wiki/Vert.x-code-style-guidelines: May require some reformatting.

pk-work · 2025-06-30T06:44:16Z

src/main/java/io/vertx/openapi/contract/OpenAPIContract.java

@@ -46,7 +43,7 @@ public interface OpenAPIContract {
   * @return A succeeded {@link Future} holding an {@link OpenAPIContract} instance, otherwise a failed {@link Future}.
   */
  static Future<OpenAPIContract> from(Vertx vertx, String unresolvedContractPath) {
-    return readYamlOrJson(vertx, unresolvedContractPath).compose(json -> from(vertx, json));
+    return builder(vertx).setContract(unresolvedContractPath).build();


Should we explicitly mention, that we also support YAML files?

In the naming of the methods? Or in the javadoc?

In the javadoc

I added it to the javadoc of the builder in 8fe103e

pk-work · 2025-06-30T07:11:27Z

src/main/java/io/vertx/openapi/contract/OpenAPIContractBuilder.java

+   * @return The builder, for a fluent interface
+   */
+  public OpenAPIContractBuilder setContract(String contractPath) {
+    this.contractFile = contractPath;


What is it now, Path or File?

I will use path at every place

I replaced all occurences of file and replaced it with path

pk-work · 2025-06-30T07:16:19Z

src/main/java/io/vertx/openapi/contract/OpenAPIContract.java

@@ -57,7 +54,11 @@ static Future<OpenAPIContract> from(Vertx vertx, String unresolvedContractPath)
   * @return A succeeded {@link Future} holding an {@link OpenAPIContract} instance, otherwise a failed {@link Future}.
   */
  static Future<OpenAPIContract> from(Vertx vertx, JsonObject unresolvedContract) {
-    return from(vertx, unresolvedContract, emptyMap());
+    if (unresolvedContract == null)
+      return Future.failedFuture(OpenAPIContractException.createInvalidContract("Spec must not be null"));


I saw this check is now made in the Builder and also throws a BuilderException which makes more sense. We should not throw it here.

Of course this is kind of breaking, so we should mention it in the release notes. But it is allowed, we are still in Technical Preview and the impact is very low.

I left it here to not break existing tests. If it is no problem to remove it, I will remove it and the corresponding test(s).

pk-work · 2025-06-30T08:21:24Z

src/main/java/io/vertx/openapi/contract/OpenAPIContractBuilder.java

+    var resolvedContracts = Future
+      .succeededFuture(additionalContracts)
+      .compose(x -> readContractFiles()
+        .map(r -> {
+          var all = new HashMap<>(x);
+          all.putAll(r);
+          return all;
+        }));


Suggested change

var resolvedContracts = Future

.succeededFuture(additionalContracts)

.compose(x -> readContractFiles()

.map(r -> {

var all = new HashMap<>(x);

all.putAll(r);

return all;

}));

var allAdditionalContracts = readContractFiles()

.map(resolvedFiles -> {

var all = new HashMap<>(additionalContracts);

all.putAll(resolvedFiles);

return all;

});

Good point to reduce unnecessary code. Is corrected in 32fe992

pk-work · 2025-06-30T08:24:02Z

src/main/java/io/vertx/openapi/contract/OpenAPIContractBuilder.java

+      });
+  }
+
+  private Future<OpenAPIContract> buildOpenAPIContract(JsonObject unresolvedContract,


Suggested change

private Future<OpenAPIContract> buildOpenAPIContract(JsonObject unresolvedContract,

private Future<OpenAPIContract> buildOpenAPIContract(JsonObject resolvedContract,

Now it is resolved, isn't it?

Is corrected in 2dd5ae0

pk-work · 2025-06-30T08:41:42Z

src/main/java/io/vertx/openapi/contract/OpenAPIContractBuilder.java

+      return failedFuture(createInvalidContract("Spec must not be null"));
+    }


I think this branch is not possible, it is also not tested. Please add a test case for this branch, or remove it.

Is removed in 494d5fe

pk-work · 2025-06-30T11:25:37Z

src/main/java/io/vertx/openapi/contract/OpenAPIContractBuilder.java

+  }
+
+  private Future<OpenAPIContract> buildOpenAPIContract(JsonObject unresolvedContract,
+                                                       Map<String, JsonObject> additionalContractFiles) {


Suggested change

Map<String, JsonObject> additionalContractFiles) {

Map<String, JsonObject> additionalContracts) {

This are no longer contract files, they are resolved

Is corrected in 2dd5ae0

pk-work · 2025-06-30T11:26:31Z

src/main/java/io/vertx/openapi/contract/OpenAPIContractBuilder.java

+        List<Future<?>> validationFutures = new ArrayList<>(additionalContractFiles.size());
+        for (String ref : additionalContractFiles.keySet()) {
+          // Todo: As soon a more modern Java version is used the validate part could be extracted in a private static
+          //  method and reused below.
+          JsonObject file = additionalContractFiles.get(ref);
+          Future<?> validationFuture = version.validateAdditionalContractFile(vertx, repository, file)
+            .compose(v -> vertx.executeBlocking(() -> repository.dereference(ref, JsonSchema.of(ref, file))));
+
+          validationFutures.add(validationFuture);
+        }
+        return Future.all(validationFutures).map(repository);


Suggested change

List<Future<?>> validationFutures = new ArrayList<>(additionalContractFiles.size());

for (String ref : additionalContractFiles.keySet()) {

// Todo: As soon a more modern Java version is used the validate part could be extracted in a private static

// method and reused below.

JsonObject file = additionalContractFiles.get(ref);

Future<?> validationFuture = version.validateAdditionalContractFile(vertx, repository, file)

.compose(v -> vertx.executeBlocking(() -> repository.dereference(ref, JsonSchema.of(ref, file))));

validationFutures.add(validationFuture);

}

return Future.all(validationFutures).map(repository);

List<Future<?>> validationFutures = new ArrayList<>(additionalContractFiles.size());

additionalContractFiles.forEach((ref, additionalContract) -> {

Future<?> validationFuture = version.validateAdditionalContractFile(vertx, repository, additionalContract)

.compose(v -> vertx.executeBlocking(() -> repository.dereference(ref, JsonSchema.of(ref, additionalContract))));

validationFutures.add(validationFuture);

});

return Future.all(validationFutures).map(repository);

Of course variables need to be renamed.

Here the contract file naming is used in another class. I corrected the naming in 663d164 and implemented your foreach suggestion in a8bd99a

src/main/java/io/vertx/openapi/contract/OpenAPIContractBuilder.java

pk-work · 2025-06-30T11:43:10Z

src/test/java/io/vertx/tests/contract/OpenAPIContractBuilderTest.java

+ */
+@ExtendWith(VertxExtension.class)
+@DisplayNameGeneration(DisplayNameGenerator.ReplaceUnderscores.class)
+public class OpenAPIContractBuilderTest {


Please have a look into class ResourceHelper which is also used in OpenAPIContractTest. There are some useful helper methods.

Refactored strings to constants in 710040a

Will allow to add new fields to the contract setup without requiring to change or to add new factory methods.

…x#101

…tracts, additionalContractPaths

… now covered by the OpenApiContractBuilder

Variable is named file, but actually is a contract part

pk-work · 2025-06-30T15:31:38Z

src/main/java/io/vertx/openapi/contract/OpenAPIContract.java

-   * @param additionalContractFiles The additional contract files
+   * @param vertx                       The related Vert.x instance.
+   * @param contract                    The unresolved contract.
+   * @param additionalContractPartPaths The additional contract part paths


Suggested change

* @param additionalContractPartPaths The additional contract part paths

* @param additionalContractParts The additional contract parts

Fixed in 01ba794

pk-work · 2025-06-30T15:33:40Z

src/main/java/io/vertx/openapi/contract/OpenAPIContractBuilder.java

+/**
+ * Builder for OpenAPIContracts.<br>
+ *
+ * In the simplest case (you only have one contract) you must either provide a path to your openapi-contract in json


I thought we mentioned it in the JavaDoc of the methods which allows to specify a contract path or additional contract part paths

pk-work · 2025-06-30T15:34:47Z

src/main/java/io/vertx/openapi/contract/OpenAPIContractBuilder.java

+  }
+
+  /**
+   * Puts a contract that is referenced by the main contract. This method can be


Suggested change

* Puts a contract that is referenced by the main contract. This method can be

* Puts an additional contract part that is referenced by the main contract. This method can be

Fixed in 01ba794

pk-work · 2025-06-30T15:36:16Z

src/main/java/io/vertx/openapi/contract/OpenAPIContractBuilder.java

+
+  /**
+   * Puts a contract that is referenced by the main contract. This method can be
+   * called multiple times to add multiple referenced contracts. Overrides a previously


Suggested change

* called multiple times to add multiple referenced contracts. Overrides a previously

* called multiple times to add multiple referenced additional contract parts. Overrides a previously

Fixed in 01ba794

pk-work · 2025-06-30T15:36:30Z

src/main/java/io/vertx/openapi/contract/OpenAPIContractBuilder.java

+  /**
+   * Puts a contract that is referenced by the main contract. This method can be
+   * called multiple times to add multiple referenced contracts. Overrides a previously
+   * added contract when the same key is used.


Suggested change

* added contract when the same key is used.

* added additional contract part when the same key is used.

Fixed in 01ba794

pk-work · 2025-06-30T15:44:23Z

src/main/java/io/vertx/openapi/contract/OpenAPIContractBuilder.java

+   * called multiple times to add multiple referenced contracts.
+   *
+   * @param key          The unique key for the contract.
+   * @param contractPart The contract object.


Suggested change

* @param contractPart The contract object.

* @param contractPart The additional contract part.

Fixed in 01ba794

pk-work · 2025-06-30T15:44:58Z

src/main/java/io/vertx/openapi/contract/OpenAPIContractBuilder.java

+  }
+
+  /**
+   * Uses the contracts from the provided map to resolve referenced contracts.


Suggested change

* Uses the contracts from the provided map to resolve referenced contracts.

* Uses the additional contract parts from the provided map to resolve referenced additional contract parts.

Fixed in 01ba794

pk-work · 2025-06-30T15:45:23Z

src/main/java/io/vertx/openapi/contract/OpenAPIContractBuilder.java

+
+  /**
+   * Uses the contracts from the provided map to resolve referenced contracts.
+   * Replaces all previously put contracts by {@link #putAdditionalContractPart(String, JsonObject)}.


Suggested change

* Replaces all previously put contracts by {@link #putAdditionalContractPart(String, JsonObject)}.

* Replaces all previously put additional contract parts by {@link #putAdditionalContractPart(String, JsonObject)}.

Fixed in 01ba794

pk-work · 2025-06-30T15:45:47Z

src/main/java/io/vertx/openapi/contract/OpenAPIContractBuilder.java

+  /**
+   * Uses the contracts from the provided map to resolve referenced contracts.
+   * Replaces all previously put contracts by {@link #putAdditionalContractPart(String, JsonObject)}.
+   * If the same key is used also replaces the contracts set by {@link #putAdditionalContractPartPath(String, String)}


Suggested change

* If the same key is used also replaces the contracts set by {@link #putAdditionalContractPartPath(String, String)}

* If the same key is used also replaces the additional contract part paths set by {@link #putAdditionalContractPartPath(String, String)}

Fixed in 01ba794

pk-work · 2025-06-30T15:51:32Z

src/main/java/io/vertx/openapi/contract/OpenAPIVersion.java

-import io.vertx.json.schema.JsonSchemaValidationException;
-import io.vertx.json.schema.OutputUnit;
-import io.vertx.json.schema.SchemaRepository;
+import io.vertx.json.schema.*;


no star imports

https://www.jetbrains.com/help/idea/creating-and-optimizing-imports.html#disable-wildcards-for-class

Fixed in c8858f8

lukasjelonek force-pushed the feature/builder branch from b01e336 to 765af73 Compare June 12, 2025 08:58

lukasjelonek mentioned this pull request Jun 12, 2025

[WIP] Add support for custom media types #101

Open

pk-work requested changes Jun 30, 2025

View reviewed changes

lukasjelonek added 9 commits June 30, 2025 16:42

Add builder for OpenAPIContract.

b2696c8

Will allow to add new fields to the contract setup without requiring to change or to add new factory methods.

Rename fields and methods according to discussions in PR eclipse-vert…

f7fc195

…x#101

Fix: Inconsistent naming of contract, contractPath, and additionalCon…

f029be7

…tracts, additionalContractPaths

Remove throwing OpenAPIContractException for null contract as this is…

d8231c6

… now covered by the OpenApiContractBuilder

Use ResourceHelper where applicable

ae0db47

Remove unnecessary future creation. Improve variable naming.

8d71d36

Remove unreachable branch

765642f

Fix: Confusing naming of method parameter

ae2a70f

Variable is named file, but actually is a contract part

Replace for-loop with stream.map

0f55864

lukasjelonek force-pushed the feature/builder branch from a8bd99a to 0f55864 Compare June 30, 2025 14:56

lukasjelonek added 2 commits June 30, 2025 17:17

Fix: inconsistent usage of contract path/part

cb5643b

Add basic documentation to the OpenAPIContractBuilder

8fe103e

pk-work requested changes Jun 30, 2025

View reviewed changes

Revert accidentally introduced star import

c8858f8

lukasjelonek force-pushed the feature/builder branch from e7495aa to e22e7af Compare July 1, 2025 06:21

lukasjelonek added 2 commits July 1, 2025 08:29

Fix: inconsistent naming of contract parts in javadoc

01ba794

Refactor: Extract strings used multiple times to constants

710040a

lukasjelonek force-pushed the feature/builder branch from e22e7af to 710040a Compare July 1, 2025 06:30

eclipse-vertx deleted a comment from lukasjelonek Jul 1, 2025

pk-work and others added 2 commits July 1, 2025 22:29

fix: fix JavaDoc and small improvements

02f986e

Fix: contract part path is used where contract part is meant in javadoc

50ab162

pk-work merged commit 0087153 into eclipse-vertx:main Jul 2, 2025
5 checks passed

pk-work deleted the feature/builder branch July 2, 2025 15:03

	private Future<OpenAPIContract> buildOpenAPIContract(JsonObject unresolvedContract,
	private Future<OpenAPIContract> buildOpenAPIContract(JsonObject resolvedContract,

		return failedFuture(createInvalidContract("Spec must not be null"));
		}

	Map<String, JsonObject> additionalContractFiles) {
	Map<String, JsonObject> additionalContracts) {

	* @param additionalContractPartPaths The additional contract part paths
	* @param additionalContractParts The additional contract parts

	* Puts a contract that is referenced by the main contract. This method can be
	* Puts an additional contract part that is referenced by the main contract. This method can be

	* called multiple times to add multiple referenced contracts. Overrides a previously
	* called multiple times to add multiple referenced additional contract parts. Overrides a previously

	* added contract when the same key is used.
	* added additional contract part when the same key is used.

	* @param contractPart The contract object.
	* @param contractPart The additional contract part.

	* Uses the contracts from the provided map to resolve referenced contracts.
	* Uses the additional contract parts from the provided map to resolve referenced additional contract parts.

	* Replaces all previously put contracts by {@link #putAdditionalContractPart(String, JsonObject)}.
	* Replaces all previously put additional contract parts by {@link #putAdditionalContractPart(String, JsonObject)}.

	* If the same key is used also replaces the contracts set by {@link #putAdditionalContractPartPath(String, String)}
	* If the same key is used also replaces the additional contract part paths set by {@link #putAdditionalContractPartPath(String, String)}

Add builder for OpenAPIContract. #103

Add builder for OpenAPIContract. #103

Uh oh!

Conversation

lukasjelonek commented Jun 12, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lukasjelonek Jul 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lukasjelonek Jul 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

lukasjelonek Jul 1, 2025 •

edited

Loading

lukasjelonek Jul 1, 2025 •

edited

Loading

lukasjelonek Jul 1, 2025 •

edited

Loading

lukasjelonek Jul 1, 2025 •

edited

Loading