Presentation of the Vert.x-Swagger project

This post is an in­tro­duc­tion to the Vert.x-​Swagger project, and de­scribe how to use the Swagger-Codegen plug­in and the SwaggerRouter class.

Eclipse Vert.x & Swagger

Vert.x and Vert.x Web are very con­ve­nient to write REST API and es­pe­cially the Router which is very use­ful to man­age all re­sources of an API.

But when I start a new API, I usu­ally use the “design-​first” ap­proach and Swag­ger is my best friend to de­fine what my API is sup­posed to do. And then, comes the “bor­ing” part of the job : con­vert the swag­ger file con­tent into java code. That’s al­ways the same : re­sources, op­er­a­tions, mod­els…

For­tu­nately, Swag­ger pro­vides a code­gen tool : Swagger-​Codegen. With this tool, you can gen­er­ate a server stub based on your swag­ger de­f­i­n­i­tion file. How­ever, even if this gen­er­a­tor pro­vides many dif­fer­ent lan­guages and frame­work, Vert.X is miss­ing.

This is where the Vert.x-​Swagger project comes in.

The project

Vert.x-​Swagger is a maven project pro­vid­ing 2 mod­ules.

vertx-swagger-codegen

It’s a Swagger-​Codegen plug­in, which add the ca­pa­bil­ity of gen­er­at­ing a Java Vert.x Web­Server to the gen­er­a­tor.

The gen­er­ated server mainly con­tains :

• POJOs for definitions
• one Ver­ti­cle per tag
• one Main­Ver­ti­cle, which man­age oth­ers APIVer­ti­cle and start an HttpServer.

vertx-swagger-router

The main class of this mod­ule is SwaggerRouter. It’s more or less a Fac­tory (and maybe I should re­name the class) that can cre­ate a Router, using the swag­ger de­f­i­n­i­tion file to con­fig­ure all the routes. For each route, it ex­tracts pa­ra­me­ters from the re­quest (Query, Path, Header, Body, Form) and send them on the event­Bus, using ei­ther the operationId as the ad­dress or a com­puted id (just a pa­ra­me­ter in the con­struc­tor).

Let see how it works

Generating the server

First, choose your swag­ger de­f­i­n­i­tion. Here’s a YAML File, but it could be a JSON file:

Then, down­load these li­braries :

• swagger-​codegen-cli
• vertx-​swagger-codegen

Fi­nally, run this com­mand

java -cp /path/to/swagger-codegen-cli-2.2.2.jar:/path/to/vertx-swagger-codegen-1.0.0.jar io.swagger.codegen.SwaggerCodegen generate \
  -l java-vertx \
  -o path/to/destination/folder \
  -i path/to/swagger/definition \
  --group-id your.group.id \
  --artifact-id your.artifact.id

You should have some­thing like that in your con­sole:

[main] INFO io.swagger.parser.Swagger20Parser - reading from ./wineCellarSwagger.yaml
[main] INFO io.swagger.codegen.AbstractGenerator - writing file [path/to/destination/folder]/src/main/java/io/swagger/server/api/model/Bottle.java
[main] INFO io.swagger.codegen.AbstractGenerator - writing file [path/to/destination/folder]/src/main/java/io/swagger/server/api/model/CellarInformation.java
[main] INFO io.swagger.codegen.AbstractGenerator - writing file [path/to/destination/folder]/src/main/java/io/swagger/server/api/verticle/BottlesApi.java
[main] INFO io.swagger.codegen.AbstractGenerator - writing file [path/to/destination/folder]/src/main/java/io/swagger/server/api/verticle/BottlesApiVerticle.java
[main] INFO io.swagger.codegen.AbstractGenerator - writing file [path/to/destination/folder]/src/main/java/io/swagger/server/api/verticle/InformationApi.java
[main] INFO io.swagger.codegen.AbstractGenerator - writing file [path/to/destination/folder]/src/main/java/io/swagger/server/api/verticle/InformationApiVerticle.java
[main] INFO io.swagger.codegen.AbstractGenerator - writing file [path/to/destination/folder]/src/main/resources/swagger.json
[main] INFO io.swagger.codegen.AbstractGenerator - writing file [path/to/destination/folder]/src/main/java/io/swagger/server/api/MainApiVerticle.java
[main] INFO io.swagger.codegen.AbstractGenerator - writing file [path/to/destination/folder]/src/main/resources/vertx-default-jul-logging.properties
[main] INFO io.swagger.codegen.AbstractGenerator - writing file [path/to/destination/folder]/pom.xml
[main] INFO io.swagger.codegen.AbstractGenerator - writing file [path/to/destination/folder]/README.md
[main] INFO io.swagger.codegen.AbstractGenerator - writing file [path/to/destination/folder]/.swagger-codegen-ignore

And this in your des­ti­na­tion folder:

What have been created ?

As you can see in 1, the vertx-​swagger-codegen plug­in has cre­ated one POJO by definition in the swag­ger file.

Example : the bottle definition

In 2a and 2b you can find :

• an in­ter­face which con­tains a func­tion per operation
• a ver­ti­cle which de­fines all operationId and cre­ate Event­Bus con­sumers

Example : the Bottles interface

Example : the Bottles verticle

… and now ?

Line 23 of BottlesApiVerticle.java, you can see this

BottlesApi service = new BottlesApiImpl();

This line will not com­pile until the BottlesApiImpl class is cre­ated.

In all XXXAPIVer­ti­cles, you will find a vari­able called ser­vice. It is a XXXAPI type and it is in­stan­ci­ated with a XXXAPIImpl con­truc­tor. This class does not exist yet since it is the busi­ness of your API.

And so you will have to cre­ate these im­ple­men­ta­tions.

Fine, but what if I don’t want to build my API like this ?

Well, Vert.x is un­opin­ion­ated but the way the vertx-​swagger-codegen cre­ates the server stub is not. So if you want to im­ple­ment your API the way you want, while en­joy­ing dy­namic rout­ing based on a swag­ger file, the vertx-​swagger-router li­brary can be used stand­alone.

Just im­port this jar into your project:

You will be able to cre­ate your Router like this:

FileSystem vertxFileSystem = vertx.fileSystem();
vertxFileSystem.readFile("***YOUR_SWAGGER_FILE***", readFile -> {
    if (readFile.succeeded()) {
        Swagger swagger = new SwaggerParser().parse(readFile.result().toString(Charset.forName("utf-8"))); 
        Router swaggerRouter = SwaggerRouter.swaggerRouter(Router.router(vertx), swagger, vertx.eventBus(), new OperationIdServiceIdResolver());
        [...]
   } else {
        [...]
   }
});

Conclusion

Vert.x and Swag­ger are great tools to build and doc­u­ment an API but using both in the same project can be painful. The Vert.x-​Swagger project was made to save time, let­ting the de­vel­op­ers fo­cus­ing on busi­ness code. It can be seen as an API frame­work over Vert.X.

You can also use the SwaggerRouter in your own project with­out using Swagger-​Codegen.

In fu­ture re­leases, more in­for­ma­tion from the swag­ger file will be used to con­fig­ure the router and cer­tainly oth­ers lan­guages will be sup­ported.

Thanks for read­ing.