Annotation-based Swagger documentation for Vert.x

Question

Is there any annotation based Swagger Documentation creator available for Vert.x yet ? The rest end points are all managed using routers and as such if there is any way available to generate the Swagger documentation, that would be great. I've gone through the Java Jersey based documentation creator using various annotations, but couldn't find anything for the Vert.x documentation. The official swagger wiki on Git Hub also doesn't house any document related to Vert.x documentations.

Answer 1

Since this question was asked Swagger has been named OpenAPI and Vert.x offers the Web API Contract module. Using this anupsaund created the vertx-auto-swagger repo (in turn based on vertx-openapi-spec-generator). It does:

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

Which then allows annotations as follows:

@Operation(summary = "Find products by ID", method = "GET", operationId = "product/:productId",
    tags = {
        "Product"
    },
    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':'https://images.pexels.com/photos/1112597/pexels-photo-1112597.jpeg'," +
                            "'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.")
    }
)