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: http://anupsaund.com/how-to-generate-openapi-3-0-swagger-spec-from-vertx-java-and-serve-it-via-swagger-ui
- 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.
@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.")
}
)
Dependancies: Maven, JAVA and a JAVA IDE is helpful.
- Clone the repository and use Maven to install dependancies.
- 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
- After tha application has launched, go to http://localhost:8080/doc/index.html
Goes to Christos Karatzas for creating the generator class which has been used and enhanced for this respository:
His original repository is available at: https://github.com/ckaratzas/vertx-openapi-spec-generator