Standards
API docs

Vert.x OpenAPI Router

Preview

Vert.x OpenAPI Router is based on Vert.x OpenAPI and only provides the router functionality.

Vert.x OpenAPI Router can:

  • generate a router according to your OpenAPI contract, with correct paths & methods.

Using Vert.x OpenAPI Router

To use Vert.x OpenAPI Router, add the following dependency to the dependencies section of your build descriptor:

  • Maven (in your pom.xml):

<dependency>
 <groupId>io.vertx</groupId>
 <artifactId>vertx-web-openapi-router</artifactId>
 <version>4.5.11</version>
</dependency>

  • Gradle (in your build.gradle file):

dependencies {
 compile 'io.vertx:vertx-web-openapi-router:4.5.11'
}

RouterBuilder

With the RouterBuilder you can easily generate a Vert.x Web Router based on the passed OpenAPIContract.

OpenAPIContract contract = getContract();
RouterBuilder routerBuilder = RouterBuilder.create(vertx, contract);
Router router = routerBuilder.createRouter();

// In case that a BodyHandler was applied before, it is necessary to pass a RequestExtractor
RouterBuilder.create(vertx, contract, RequestExtractor.withBodyHandler());

The RouterBuilder provides methods to access the generated routes. These routes can then be customized by adding custom handlers or enable / disable the validation.

OpenAPIRoute getPetsRoute = routerBuilder.getRoute("getPets");

// Disables validation for this route.
getPetsRoute.setDoValidation(false);

for (OpenAPIRoute route : routerBuilder.getRoutes()) {
  // Access the operation object from the contract
  Operation operation = route.getOperation();

  // Add a custom handler
  route.addHandler(routingContext -> {
    // do something
  });

  // Add a failure handler
  route.addFailureHandler(routingContext -> {
    // do something
  });
}

After a successful validation of the incoming request, the validated parameters and request body are stored in the RoutingContext and can be accessed inside your custom handlers.

OpenAPIRoute putPetRoute = routerBuilder.getRoute("putPet");

putPetRoute.addHandler(routingContext -> {
  ValidatedRequest validatedRequest =
    routingContext.get(RouterBuilder.KEY_META_DATA_VALIDATED_REQUEST);

  validatedRequest.getBody(); // returns the body
  validatedRequest.getHeaders(); // returns the header
  // ..
  // ..
});