/vertx-web-openapi-tests

Primary LanguageJavaApache License 2.0Apache-2.0

Vert.x OpenAPI based Web Router

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:

link:src/main/java/io/vertx/howtos/openapi/APIVerticle.java[role=include]

  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:

link:src/main/java/io/vertx/howtos/openapi/APIVerticle.java[role=include]

  1. Get the response object

  2. Put Content-type: application/json header

  3. Write the response with all pets

For createPets:

link:src/main/java/io/vertx/howtos/openapi/APIVerticle.java[role=include]

  1. Get the parsed parameters container

  2. Extract the parsed body

  3. Write the 200 empty response

For showPetById:

link:src/main/java/io/vertx/howtos/openapi/APIVerticle.java[role=include]

  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:

link:src/main/java/io/vertx/howtos/openapi/APIVerticle.java[role=include]

  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
[{"id":1,"name":"Fufi","tag":"ABC"},{"id":2,"name":"Garfield","tag":"ABC"},{"id":3,"name":"Puffa","tag":"ABC"}]

$ curl http://localhost:8080/pets/3
{"id":3,"name":"Puffa","tag":"ABC"}

$ 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
[{"id":1,"name":"Fufi","tag":"ABC"},{"id":2,"name":"Garfield","tag":"ABC"},{"id":3,"name":"Puffa","tag":"ABC"},{"id":4,"name":"Alan"}]

References