Add custom mediatypes

Author: lukasjelonek

src/main/asciidoc/index.adoc

@@ -151,3 +151,12 @@ The validation can fail for formal reasons, such as the wrong format for a param
 However, validation can of course also fail because the content does not match the defined schema.
 In this case a {@link io.vertx.openapi.validation.SchemaValidationException} is thrown.
 It is a subclass of _ValidatorException_ and provides access to the related {@link io.vertx.json.schema.OutputUnit} to allow further analysis of the error.
+
+=== Add custom media types
+
+By default a commonly used set of media types is supported. In case you need support for additional media types you have to register via the OpenAPIContractBuilder and a MediaTypeRegistry.
+
+[source,$lang]
+----
+{@link examples.ContractExamples#createContractWithCustomMediaTypes}
+----

src/main/java/examples/ContractExamples.java

@@ -18,7 +18,10 @@
 import io.vertx.openapi.contract.Operation;
 import io.vertx.openapi.contract.Parameter;
 import io.vertx.openapi.contract.Path;
-
+import io.vertx.openapi.mediatype.ContentAnalyserFactory;
+import io.vertx.openapi.mediatype.MediaTypeRegistration;
+import io.vertx.openapi.mediatype.MediaTypePredicate;
+import io.vertx.openapi.mediatype.MediaTypeRegistry;
 import java.util.HashMap;
 import java.util.Map;
 
@@ -61,4 +64,23 @@ public void pathParameterOperationExample() {
   private OpenAPIContract getContract() {
     return null;
   }
+
+  public void createContractWithCustomMediaTypes(Vertx vertx) {
+    String pathToContract = ".../.../myContract.json"; // json or yaml
+    String pathToComponents = ".../.../myComponents.json"; // json or yaml
+
+    Future<OpenAPIContract> contract =
+      OpenAPIContract.builder(vertx)
+        .setContractPath(pathToContract)
+        .setAdditionalContractPartPaths(Map.of(
+          "https://example.com/pet-components", pathToComponents))
+        .mediaTypeRegistry(
+          MediaTypeRegistry.createDefault()
+            .register(
+              MediaTypeRegistration.create(
+                MediaTypePredicate.ofExactTypes("text/my-custom-type+json"),
+                ContentAnalyserFactory.json()))
+        )
+        .build();
+  }
 }

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

@@ -27,20 +27,36 @@
 @VertxGen
 public interface MediaType extends OpenAPIObject {
 
+  @Deprecated
   String APPLICATION_JSON = "application/json";
+  @Deprecated
   String APPLICATION_JSON_UTF8 = APPLICATION_JSON + "; charset=utf-8";
+  @Deprecated
   String MULTIPART_FORM_DATA = "multipart/form-data";
+  @Deprecated
   String APPLICATION_HAL_JSON = "application/hal+json";
+  @Deprecated
   String APPLICATION_OCTET_STREAM = "application/octet-stream";
+  @Deprecated
   String TEXT_PLAIN = "text/plain";
+  @Deprecated
   String TEXT_PLAIN_UTF8 = TEXT_PLAIN + "; charset=utf-8";
+  @Deprecated
   List<String> SUPPORTED_MEDIA_TYPES = List.of(APPLICATION_JSON, APPLICATION_JSON_UTF8, MULTIPART_FORM_DATA,
       APPLICATION_HAL_JSON, APPLICATION_OCTET_STREAM, TEXT_PLAIN, TEXT_PLAIN_UTF8);
 
+  /**
+   * @deprecated The {@link io.vertx.openapi.mediatype.MediaTypeRegistry} replaced the usage of this static method.
+   */
+  @Deprecated
   static boolean isMediaTypeSupported(String type) {
     return SUPPORTED_MEDIA_TYPES.contains(type.toLowerCase()) || isVendorSpecificJson(type);
   }
 
+  /**
+   * @deprecated The {@link io.vertx.openapi.mediatype.MediaTypeRegistry} replaced the usage of this static method.
+   */
+  @Deprecated
   static boolean isVendorSpecificJson(String type) {
     return VendorSpecificJson.matches(type);
   }

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

@@ -12,13 +12,15 @@
 
 package io.vertx.openapi.contract;
 
+import io.vertx.codegen.annotations.GenIgnore;
 import io.vertx.codegen.annotations.Nullable;
 import io.vertx.codegen.annotations.VertxGen;
 import io.vertx.core.Future;
 import io.vertx.core.Vertx;
 import io.vertx.core.http.HttpMethod;
 import io.vertx.core.json.JsonObject;
 import io.vertx.json.schema.SchemaRepository;
+import io.vertx.openapi.mediatype.MediaTypeRegistry;
 import java.util.List;
 import java.util.Map;
 
@@ -175,4 +177,12 @@ static Future<OpenAPIContract> from(Vertx vertx, JsonObject contract,
    */
   @Nullable
   SecurityScheme securityScheme(String name);
+
+  /**
+   * Gets the mediatype registry.
+   *
+   * @return The registry.
+   */
+  @GenIgnore
+  MediaTypeRegistry getMediaTypeRegistry();
 }

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

@@ -25,6 +25,7 @@
 import io.vertx.json.schema.JsonSchemaValidationException;
 import io.vertx.openapi.contract.impl.OpenAPIContractImpl;
 import io.vertx.openapi.impl.Utils;
+import io.vertx.openapi.mediatype.MediaTypeRegistry;
 import java.util.HashMap;
 import java.util.Map;
 import java.util.stream.Collectors;
@@ -57,6 +58,7 @@ public OpenAPIContractBuilderException(String message) {
   private JsonObject contract;
   private final Map<String, String> additionalContractPartPaths = new HashMap<>();
   private final Map<String, JsonObject> additionalContractParts = new HashMap<>();
+  private MediaTypeRegistry registry;
 
   public OpenAPIContractBuilder(Vertx vertx) {
     this.vertx = vertx;
@@ -153,12 +155,19 @@ public OpenAPIContractBuilder setAdditionalContractParts(Map<String, JsonObject>
     return this;
   }
 
+  public OpenAPIContractBuilder mediaTypeRegistry(MediaTypeRegistry registry) {
+    this.registry = registry;
+    return this;
+  }
+
   /**
    * Builds the contract.
    *
    * @return The contract.
    */
   public Future<OpenAPIContract> build() {
+    if (this.registry == null)
+      this.registry = MediaTypeRegistry.createDefault();
 
     if (contractPath == null && contract == null) {
       return Future.failedFuture(new OpenAPIContractBuilderException(
@@ -192,7 +201,7 @@ private Future<OpenAPIContract> buildOpenAPIContract() {
             return failedFuture(createInvalidContract(null, e));
           }
         })
-            .map(resolvedSpec -> new OpenAPIContractImpl(resolvedSpec, version, repository)))
+            .map(resolvedSpec -> new OpenAPIContractImpl(resolvedSpec, version, repository, registry)))
         .recover(e -> {
           // Convert any non-openapi exceptions into an OpenAPIContractException
           if (e instanceof OpenAPIContractException) {

src/main/java/io/vertx/openapi/contract/impl/OpenAPIContractImpl.java

@@ -35,6 +35,7 @@
 import io.vertx.openapi.contract.SecurityRequirement;
 import io.vertx.openapi.contract.SecurityScheme;
 import io.vertx.openapi.contract.Server;
+import io.vertx.openapi.mediatype.MediaTypeRegistry;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Map;
@@ -65,13 +66,17 @@ public class OpenAPIContractImpl implements OpenAPIContract {
 
   private final Map<String, SecurityScheme> securitySchemes;
 
+  private final MediaTypeRegistry mediaTypes;
+
   // VisibleForTesting
   final String basePath;
 
-  public OpenAPIContractImpl(JsonObject resolvedSpec, OpenAPIVersion version, SchemaRepository schemaRepository) {
+  public OpenAPIContractImpl(JsonObject resolvedSpec, OpenAPIVersion version, SchemaRepository schemaRepository,
+      MediaTypeRegistry mediaTypes) {
     this.rawContract = resolvedSpec;
     this.version = version;
     this.schemaRepository = schemaRepository;
+    this.mediaTypes = mediaTypes;
 
     servers = resolvedSpec
         .getJsonArray(KEY_SERVERS, EMPTY_JSON_ARRAY)
@@ -95,7 +100,7 @@ public OpenAPIContractImpl(JsonObject resolvedSpec, OpenAPIVersion version, Sche
         .stream()
         .filter(JsonSchema.EXCLUDE_ANNOTATION_ENTRIES)
         .map(pathEntry -> new PathImpl(basePath, pathEntry.getKey(), (JsonObject) pathEntry.getValue(),
-            securityRequirements))
+            securityRequirements, mediaTypes))
         .collect(toList());
 
     List<PathImpl> sortedPaths = applyMountOrder(unsortedPaths);
@@ -232,4 +237,9 @@ public List<SecurityRequirement> getSecurityRequirements() {
   public SecurityScheme securityScheme(String name) {
     return securitySchemes.get(name);
   }
+
+  @Override
+  public MediaTypeRegistry getMediaTypeRegistry() {
+    return mediaTypes;
+  }
 }

src/main/java/io/vertx/openapi/contract/impl/OperationImpl.java

@@ -34,6 +34,7 @@
 import io.vertx.openapi.contract.RequestBody;
 import io.vertx.openapi.contract.Response;
 import io.vertx.openapi.contract.SecurityRequirement;
+import io.vertx.openapi.mediatype.MediaTypeRegistry;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
@@ -67,7 +68,7 @@ public class OperationImpl implements Operation {
 
   public OperationImpl(String absolutePath, String path, HttpMethod method, JsonObject operationModel,
       List<Parameter> pathParameters, Map<String, Object> pathExtensions,
-      List<SecurityRequirement> globalSecReq) {
+      List<SecurityRequirement> globalSecReq, MediaTypeRegistry registry) {
     this.absolutePath = absolutePath;
     this.operationId = operationModel.getString(KEY_OPERATION_ID);
     this.method = method;
@@ -119,7 +120,7 @@ public OperationImpl(String absolutePath, String path, HttpMethod method, JsonOb
     if (requestBodyJson == null || requestBodyJson.isEmpty()) {
       this.requestBody = null;
     } else {
-      this.requestBody = new RequestBodyImpl(requestBodyJson, operationId);
+      this.requestBody = new RequestBodyImpl(requestBodyJson, operationId, registry);
     }
 
     JsonObject responsesJson = operationModel.getJsonObject(KEY_RESPONSES, EMPTY_JSON_OBJECT);
@@ -128,7 +129,7 @@ public OperationImpl(String absolutePath, String path, HttpMethod method, JsonOb
       throw createInvalidContract(msg);
     }
     defaultResponse = responsesJson.stream().filter(entry -> "default".equalsIgnoreCase(entry.getKey())).findFirst()
-        .map(entry -> new ResponseImpl((JsonObject) entry.getValue(), operationId)).orElse(null);
+        .map(entry -> new ResponseImpl((JsonObject) entry.getValue(), operationId, registry)).orElse(null);
     responses =
         unmodifiableMap(
             responsesJson
@@ -137,7 +138,7 @@ public OperationImpl(String absolutePath, String path, HttpMethod method, JsonOb
                 .filter(JsonSchema.EXCLUDE_ANNOTATIONS)
                 .filter(RESPONSE_CODE_PATTERN.asPredicate())
                 .collect(
-                    toMap(Integer::parseInt, key -> new ResponseImpl(responsesJson.getJsonObject(key), operationId))));
+                    toMap(Integer::parseInt, key -> new ResponseImpl(responsesJson.getJsonObject(key), operationId, registry))));
   }
 
   @Override

src/main/java/io/vertx/openapi/contract/impl/PathImpl.java

@@ -31,6 +31,7 @@
 import io.vertx.openapi.contract.Parameter;
 import io.vertx.openapi.contract.Path;
 import io.vertx.openapi.contract.SecurityRequirement;
+import io.vertx.openapi.mediatype.MediaTypeRegistry;
 import java.util.ArrayList;
 import java.util.HashMap;
 import java.util.List;
@@ -62,7 +63,8 @@ public class PathImpl implements Path {
   private final JsonObject pathModel;
   private final String absolutePath;
 
-  public PathImpl(String basePath, String name, JsonObject pathModel, List<SecurityRequirement> globalSecReq) {
+  public PathImpl(String basePath, String name, JsonObject pathModel, List<SecurityRequirement> globalSecReq,
+      MediaTypeRegistry registry) {
     this.absolutePath = (basePath.endsWith("/") ? basePath.substring(0, basePath.length() - 1) : basePath) + name;
     this.pathModel = pathModel;
     if (name.contains("*")) {
@@ -82,7 +84,7 @@ public PathImpl(String basePath, String name, JsonObject pathModel, List<Securit
     List<Operation> ops = new ArrayList<>();
     SUPPORTED_METHODS.forEach((methodName, method) -> Optional.ofNullable(pathModel.getJsonObject(methodName))
         .map(operationModel -> new OperationImpl(absolutePath, name, method, operationModel, parameters,
-            getExtensions(), globalSecReq))
+            getExtensions(), globalSecReq, registry))
         .ifPresent(ops::add));
     this.operations = unmodifiableList(ops);
   }

src/main/java/io/vertx/openapi/contract/impl/RequestBodyImpl.java

@@ -12,8 +12,6 @@
 
 package io.vertx.openapi.contract.impl;
 
-import static io.vertx.openapi.contract.MediaType.SUPPORTED_MEDIA_TYPES;
-import static io.vertx.openapi.contract.MediaType.isMediaTypeSupported;
 import static io.vertx.openapi.contract.OpenAPIContractException.createInvalidContract;
 import static io.vertx.openapi.contract.OpenAPIContractException.createUnsupportedFeature;
 import static io.vertx.openapi.impl.Utils.EMPTY_JSON_OBJECT;
@@ -25,6 +23,7 @@
 import io.vertx.json.schema.JsonSchema;
 import io.vertx.openapi.contract.MediaType;
 import io.vertx.openapi.contract.RequestBody;
+import io.vertx.openapi.mediatype.MediaTypeRegistry;
 import java.util.Map;
 
 public class RequestBodyImpl implements RequestBody {
@@ -37,7 +36,7 @@ public class RequestBodyImpl implements RequestBody {
 
   private final Map<String, MediaType> content;
 
-  public RequestBodyImpl(JsonObject requestBodyModel, String operationId) {
+  public RequestBodyImpl(JsonObject requestBodyModel, String operationId, MediaTypeRegistry registry) {
     this.requestBodyModel = requestBodyModel;
     this.required = requestBodyModel.getBoolean(KEY_REQUIRED, false);
     JsonObject contentObject = requestBodyModel.getJsonObject(KEY_CONTENT, EMPTY_JSON_OBJECT);
@@ -48,12 +47,12 @@ public RequestBodyImpl(JsonObject requestBodyModel, String operationId) {
             .stream()
             .filter(JsonSchema.EXCLUDE_ANNOTATIONS)
             .filter(mediaTypeIdentifier -> {
-              if (isMediaTypeSupported(mediaTypeIdentifier)) {
+              if (registry.isSupported(mediaTypeIdentifier)) {
                 return true;
               }
               String msgTemplate = "Operation %s defines a request body with an unsupported media type. Supported: %s";
               throw createUnsupportedFeature(
-                  String.format(msgTemplate, operationId, join(", ", SUPPORTED_MEDIA_TYPES)));
+                  String.format(msgTemplate, operationId, join(", ", registry.supportedTypes())));
             })
             .collect(toMap(this::removeWhiteSpaces, key -> new MediaTypeImpl(key, contentObject.getJsonObject(key)))));
 

src/main/java/io/vertx/openapi/contract/impl/ResponseImpl.java

@@ -18,6 +18,7 @@
 import static io.vertx.openapi.contract.MediaType.isMediaTypeSupported;
 import static io.vertx.openapi.contract.OpenAPIContractException.createUnsupportedFeature;
 import static io.vertx.openapi.impl.Utils.EMPTY_JSON_OBJECT;
+import io.vertx.openapi.mediatype.MediaTypeRegistry;
 import static java.lang.String.join;
 import static java.util.Collections.unmodifiableMap;
 import static java.util.function.Function.identity;
@@ -45,7 +46,7 @@ public class ResponseImpl implements Response {
 
   private final JsonObject responseModel;
 
-  public ResponseImpl(JsonObject responseModel, String operationId) {
+  public ResponseImpl(JsonObject responseModel, String operationId, MediaTypeRegistry registry) {
     this.responseModel = responseModel;
 
     JsonObject headersObject = responseModel.getJsonObject(KEY_HEADERS, EMPTY_JSON_OBJECT);
@@ -68,9 +69,9 @@ public ResponseImpl(JsonObject responseModel, String operationId) {
             .filter(JsonSchema.EXCLUDE_ANNOTATIONS)
             .collect(toMap(identity(), key -> new MediaTypeImpl(key, contentObject.getJsonObject(key)))));
 
-    if (content.keySet().stream().anyMatch(type -> !isMediaTypeSupported(type))) {
+    if (content.keySet().stream().anyMatch(type -> !registry.isSupported(type))) {
       String msgTemplate = "Operation %s defines a response with an unsupported media type. Supported: %s";
-      throw createUnsupportedFeature(String.format(msgTemplate, operationId, join(", ", SUPPORTED_MEDIA_TYPES)));
+      throw createUnsupportedFeature(String.format(msgTemplate, operationId, join(", ", registry.supportedTypes())));
     }
   }