Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


TL;DR - How to get java Vert.x to automatically generate a Open API v3 spec (A.k.a. Swagger) and serve it to Swagger UI, served through Vert.x.


I needed a way to generate a swagger spec from Java code, instead of having to hand craft a swagger JSON file.

I also wanted to serve out the spec from Vert.x into Swagger UI so that it could be used by all.

There is a more detailed write up available on my blog post:

What does it do?

  1. Read Java Annotations and map them into a openAPI spec.
  2. Serve the openAPI spec out on an end point.
  3. Serve a distributable version of SwaggerUI which presents the swagger spec from point 2.

Screenshot of Swagger UI


What does a typical Java annotation look like?

@Operation(summary = "Find products by ID", method = "GET", operationId = "product/:productId",
    tags = {
    parameters = {
      @Parameter(in = ParameterIn.PATH, name = "productId",
        required = true, description = "The unique ID belonging to the product", schema = @Schema(type = "string"))
    responses = {
      @ApiResponse(responseCode = "200", description = "OK",
        content = @Content(
          mediaType = "application/json",
          encoding = @Encoding(contentType = "application/json"),
          schema = @Schema(name = "product", example =
            "{" +
              "'_id':'abc'," +
              "'title':'Red Truck'," +
              "'image_url':''," +
              "'from_date':'2018-08-30'," +
              "'to_date':'2019-08-30'," +
              "'price':'125.00'," +
              "'enabled':true" +
            implementation = Product.class)
      @ApiResponse(responseCode = "404", description = "Not found."),
      @ApiResponse(responseCode = "500", description = "Internal Server Error.")

How to get it running

Dependancies: Maven, JAVA and a JAVA IDE is helpful.

  1. Clone the repository and use Maven to install dependancies.
  2. In Intellij set up a config to run a Java Application with the following settings.
  Main Class: io.vertx.core.Launcher
  VM Options: <up to you, or leave blank>
  Program Arguments: run io.vertx.VertxAutoSwagger.MainVerticle
  1. After tha application has launched, go to http://localhost:8080/doc/index.html

Special Credit

Goes to Christos Karatzas for creating the generator class which has been used and enhanced for this respository:

His original repository is available at:


No releases published


No packages published