Replaced swagger2markup maven plugin with openapi-generator

[ppatierno]

The current build of the bridge is broken, more specifically the part related to the documentation generation.
This is because the Maven plugin we use, swagger2markup, has been abandoned (since years) and lately some of its dependencies were removed from JCenter (which seems to be also going to be dismissed by JFrog).
Several times we tried to replace it and now it's the right time.
This PR is an attempt to use the openapi-generator project to do so. This project provides several generators for clients and documentation. It's able to generate code and content starting from the OpenAPI specification.
The generator used in this PR is the asciidoc one in order to generate the documentation for our OpenAPI specification in asciidoc format without making any change in the documentation flow generation we have today (through the Makefile).

The output I have got for the official website is pretty similar to the current one with some caviets:

• it seems openapi-generator doesn't have support for generating the examples in asciidoc starting from the examples we have in the OpenAPI specification. The only workaround they provide is by using "snippets". With snippets we can put adoc examples in specific folders and they are included in the final asciidoc file. The drawback of this approach is duplication: every time we change or add a new example to the OpenAPI spec, we need to copy the corresponding snippet into the adoc file.
• today our OpenAPI spec v3 defines our "key" and "value" for some components (i.e. ConsumerRecord, ProducerRecord) by using "oneOf" because they can be array, JSON (object) or string. From a generator perspective this is something that can't be handled by the generator itself because on code and documentation side, the generator can't create meaningful objects for a language. The "oneOf" approach is instead used by the vertx-web-openapi to validate the content of the body from the HTTP request. The end result of this is that right now the field defined as "oneOf" are rendered with a custom "empty" type by the openapi-generator and they are not rendered at all by the current swagger2markup (yes! we didn't notice that but for example, if you look for ProducerRecord in the current doc, the fields key and value are completely missing).
• the generated adoc file has some duplicated sections (I opened an issue on the openapi generator project to get insights The asciidoc generator generates duplicated documentation for the same operation id OpenAPITools/openapi-generator#19659) but I also noticed that the final rendering in HTML (through the asciidoctor) contains just one, so it's not a big issue.

In general, we should continue to investigate how to improve and fix the above "issues" but right now this is the only way I see to unlock the bridge build.

[ppatierno]

I also noticed that this happened to Keycloack project in the past and they fixed by pushing the missing artifact in a personal namespace dropping JCenter. To be honest I am not so keed to this approach keycloak/keycloak#5070

[scholzj]

Ok, I guess I do not have a strong opinion on this.

[PaulRMellor]

Good to find a solution to this ongoing issue. The content maps to what we have currently. If we want to maintain a single bridge doc including the API content, considering the API is stable so we don't need to change it much, this works fine.

Otherwise, we could consider spinning off the API content and hosting HTML output that we link to from the main bridge docs. Or it is possible to include HTML content in an asciidoc book (but that might introduce other issues).