Standards
API docs
You are currently viewing the documentation for Vert.x 4.4.9. Visit the latest version of this page.

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.4.9</version>
</dependency>

  • Gradle (in your build.gradle file):

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

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
  // ..
  // ..
});