In the shiny new world of the API Economy your API definition and its enforcement is everything. The current standard for REST based APIs is OpenAPI. What it gives you is a JSON or YAML file that describes how your API looks like. There is a whole zoo of tools around that allow to visualize, edit, run Mock servers or generate client and server code.

My favorite editor for OpenAPI specs is Apicurio, a project driven by RedHat. It strikes a nice balance between being UI driven and leaving you access to the full source code of your specification.

What to do with it

Your API specification defines:

• the endpoints (a.k.a the URLS that you can use)
• the mime types that can be sent or will received
• the parameters in the path (the URL)
• the parameters in the query (the part that looks like ?color=red&shape=circle)
• the body to send and receive
• the authentication / authorization requirements
• the potential status codes (we love 2xx)

To handle all this, it smells like boilerplate or, if you are lucky, ready library. vert.x has the later. It provides the API Contract module that is designed to handle all this for you. You simply add the module to your pom.xml and load your json or yaml OpenApi specification file:

<dependency>
 <groupId>io.vertx</groupId>
 <artifactId>vertx-web-api-contract</artifactId>
 <version>3.8.1</version>
</dependency>

The documentation shows the code to turn the OpenApi speccification into a Router factory:

OpenAPI3RouterFactory.create(
  vertx,
  "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml",
  ar -> {
    if (ar.succeeded()) {
      // Spec loaded with success
      OpenAPI3RouterFactory routerFactory = ar.result();
    } else {
      // Something went wrong during router factory initialization
      Throwable exception = ar.cause();
    }
  });

As you can see, you can load the spec from an URL (there's an auth option too). So while your API is evolving using Apicurio you can live load the latest and greated from the live preview (should make some interesting breakages ;-) ).

You then add your routes using routerFactory.addHandlerByOperationId("awesomeOperation",this::awesomeOperationHandler). Vert.x doesn't use the path to match the handler, but the operationId. This allows you to update path information without breaking your code. There is a detailed how-to document describing the steps.

Generate a skeleton for vert.x

As long as you haven't specified a handler for an operation, Vert.x will automatically reply with 501 Not implemented and not throw any error. To give you a headstart, you can generate the base code. First option is to head to start.vertx.io to generate a standard project skeleton, saving you the manual work of creating all dependencies in your pom.xml file. Using "Show dependency panel" provides a convenient way to pick the modules you need.

But there are better ways. You can use an OpenAPI Generator or the advanced Vert.x Starter courtesy of Paulo Lopes. In his tool you specify what it shall generate in a dropdown that defaults to "Empty Project". Once you change that to "OpenAPI Server" the form will alloow you to upload your OpenAPI specification and you get a complete project rendered with all handler stubs including the security handler. There's also a JavaScript version available.