Аннотированная документация Swagger для Vert.x

Поскольку этот вопрос был задан, Swagger получил название OpenAPI, а Vert.x предлагает Web Модуль API Contract. Используя этот анупсаунд, был создан vertx-auto-swagger репо (в свою очередь, на основе vertx-openapi-spec-generator). Оно делает:

• Прочтите аннотации Java и сопоставьте их со спецификацией openAPI.
• Выполните спецификацию openAPI на конечной точке.
• Предоставьте распространяемую версию SwaggerUI, которая представляет спецификацию чванства из пункта 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.")
    }
)