Skip to content


Repository files navigation

Create Vert.x Web Router from an OpenAPI document

This document will show you how to use your OpenAPI document to create a Vert.x Web Router that validates and extract incoming request parameters.

What you will build

You will build a Vert.x application that manages an in-memory list of pets and serves it through the Petstore API

What you need

  • A text editor or IDE

  • Java 8 higher

  • Maven

Create a project

Here is the content of the pom.xml file you should be using:

Maven pom.xml

Load the OpenAPI document

Vert.x Web API Contract provides you RouterBuilder, an object that helps you to build the Vert.x Web Router starting from the OpenAPI specification.

To load the specification into the start method of your Verticle:

  1. If the loading succeeds, you receive a ready to use instance of RouterBuilder, otherwise

  2. you fail the deploy of the verticle

Write the handlers

Now you can fit your business logic into the Route handlers using operation(operationId).handler().

For listPets:

  1. Get the response object

  2. Put Content-type: application/json header

  3. Write the response with all pets

For createPets:

  1. Get the parsed parameters container

  2. Extract the parsed body

  3. Write the 200 empty response

For showPetById:

  1. Get the parsed parameters container

  2. Extract the parsed path parameter

  3. Search the pet

  4. If pet is present, write the pet in the response

  5. If pet is absent, fail the routing context with 404

Get the router

Now we can generate the Router and add the "Not Found" and "Bad Request" error handlers:

  1. Generate the Router from the RouterBuilder

  2. Mount the 404 not found error handler

  3. Create the error json object with exception message, if any

  4. Write the response with the error object

  5. Instantiate a Vert.x HttpServer

  6. Mount the router on the HttpServer instance

Complete code

You can find the complete source code of APIVerticle on this how-to repo.

Running the application

The APIVerticle already has a main method, so it can be used as-is to:

  1. create a Vertx context, then

  2. deploy APIVerticle.

You can run the application from:

  1. your IDE, by running the main method from the APIVerticle class, or

  2. with Maven: mvn compile exec:java

You can test your API using any command-line tool like curl:

$ curl http://localhost:8080/pets

$ curl http://localhost:8080/pets/3

$ curl http://localhost:8080/pets/5
{"code":404,"message":"Pet not found"}

$ curl -X POST -H "Content-type: application/json" --data '{"id":4,"name":"Alan"}' http://localhost:8080/pets

$ curl -X POST -H "Content-type: application/json" --data '{"id":4}' http://localhost:8080/pets
{"code":400,"message":"$.name: is missing but it is required"}

$ curl http://localhost:8080/pets


This how-to explained to you:

  1. How to create your Vert.x Web Router starting from your OpenAPI document

  2. How to extract parsed request parameters

  3. How to write Json responses

  4. How to define router wide error handlers

  5. How to start an HTTP Server and mount the generated router