Auto-generate swagger web UI for my services

[maybeec]

As a developer I would like to get a swagger web UI auto-generated in dev mode in order to easily test my service REST interface by navigating my browser to a specific URL.

tkit is providing this out-of-the box. Need to respect this when discussing possibly different solutions for #12

[matus-m]

Quarkus provides both Openapi (code first approach) and Swagger-UI support out of the box using quarkus-smallrye-openapi extension. This works fine and also provider support UI customization(based on SwaggerUI config, styling, logo etc) and loading of OpenAPI schemas from static files. There are 2 limitations though:

• API annotations have to be from the MP OpenAPI package(org.eclipse.microprofile.openapi.annotations.*) instead of Swagger annotations(io.swagger.core.v3) - they match 1:1 in most cases.
• All endpoints are processed into single schema - e.g. if you provider some internal and some public API, all operations would end up in single runtime schema.

If this is not an issue, that the built-in tooling should be the preferred solution.
In case a support for multiple separate schemas is required it can be address by a) implementing this feature in Quarkus or b) build-time schema generation(maven plugins exist) that would generate the schema(s) as static files and swagger UI would be used to serve the static files instead of live-generated one.

[GuentherJulian]

The quarkus-smallrye-openapi extension uses WebJars (swagger-ui-dist) to get the client side dependencies for the Swagger UI, such as css files. (https://github.com/smallrye/smallrye-open-api/blob/main/ui/open-api-ui/pom.xml#L95). The files from the original swagger-ui GitHub repository are used (https://github.com/swagger-api/swagger-ui/tree/master/dist).

For the index.html file, they provide a template with variables that they fill with the configured options.
https://github.com/smallrye/smallrye-open-api/blob/main/ui/open-api-ui/src/main/resources/template/index.html
https://github.com/smallrye/smallrye-open-api/blob/main/ui/open-api-ui/src/main/java/io/smallrye/openapi/ui/IndexHtmlCreator.java

To serve the index.html file they use VertX
https://github.com/quarkusio/quarkus/blob/main/extensions/swagger-ui/deployment/src/main/java/io/quarkus/swaggerui/deployment/SwaggerUiProcessor.java#L146
https://github.com/quarkusio/quarkus/blob/main/extensions/swagger-ui/runtime/src/main/java/io/quarkus/swaggerui/runtime/SwaggerUiStaticHandler.java

A way to implement it our own way could be to extend the servicedocgen maven plugin to generate the index.html file based on an own template (generation of the OpenAPI definition is already implemented), then use WebJars to get the dependencies (css, js files) and create a new extension which serves these static files within the application.

[GuentherJulian]

Created PR for servicedocgen maven plugin (mojohaus/servicedocgen-maven-plugin#31) to generate Swagger UI without need to use quarkus-smallrye-extension. The directory where the needed files should be created can be specified in the pom.xml, so they can directly served when running the application. Tested it with the Quarkus reference project and Jump-The-Queue application. To work with the Quarkus application the rest services have to be modified. The OpenApi annotations have to be removed.

[hohwille]

IMHO this story is more or less completed. We only have to complete the latest servicedocgen PR and get a 1.0.0 release from that. With that version we can fill the gaps and bring everything together.

[maybeec]

I got the reply by Julian, that we are missing swagger ui to have all setup being able to directly query your api from the swagger ui like it is available out of the box by quarkus if you use the odd annotation based service documentation.  I feel it's not a luxury but necessity in a world focusing on apis. Wdyt? 

[GuentherJulian]

With version 1.0.0 the servicedocgen maven plugin is now able to generate OpenAPI definitions and SwaggerUI. I think this issue is complete and can be closed. What do you think @maybeec @hohwille ?

[maybeec]

where can I find the tutorial or documentation on

• how to generate my openapi file out of my services?
• how do i get the swagger UI for testing my service?

until we don't have the stuff documented, I don't feel we are done. So far this feature is invisible.
Could be multiple very small katacoda tutorials!

[matus-m]

Does the servicedocgen provide any features that are not provided by the built-in openapi extension?
The openapi/swagger extension has support for multiple schema files, enabling/disableing swagger-ui, customization of swaggerui path, filtering resources. UI config, support for OAUTH authorization in swagger ui....
Plus if the developers actually add microprofile openapi annotations to properly document their endpoints and models, these would not picked up the servicedogen which only considers java code and bytecode.

The documentation for quarkus devon should imo simply point to the existing tooling from Quarkus.

[maybeec]

I think both is totally valid and we should provide both on the docs. The only major difference is, that for servicedocgen, you don't need any service documentation. It will automatically generate the swaggerui as well as the openapi document out of the blanc java rest interfaces and their javadoc. This was a huge discussion in the past in the devonfw space as most of the project didn't want to have redundant documentation for simply generating openapi or swagger ui capabilities.

[matus-m]

Quarkus-openapi also works of course if there are no documentation annotations in the code -but then the generated schema is definitely not complete, missing examples, validation rules, possible response codes for negative cases etc - just like when we use serviecdocgen. Bellow is a comparison for the output of the schemas from quarkus-openapi and servicedocgen without any microprofile annotations:

The additional point to consider, is that servicedocgen generates static resources - which would need to be handled by some custom servlet or sth to add dynamic behaviour there.
Thats why I asked for the features that servicedocgen has over the quarkus-openapi -as I am not familiar with it, when we would recommend it over the built in option.

[GuentherJulian]

Created an issue for the documentation: devonfw/devon4j#483. Feel free to add comments if you have any.
I also think we should mention both solutions. The advantage of servicedocgen is that we can use it for both Quarkus and Spring applications.