Add an Microprofile OpenAPI example

[liweinan]

No description provided.

[liweinan]

@jamezp I'm working on a SmallRye based OpenAPI example, and I've made some progresses. I plan to make the example based on the current bootable-jar example(I'll move the openapi example into separate submodules later), because it's convenient to boot the WildFly
using the wildfly-jar plugin IMHO.

Here is the jaxrs support provied by the smallrye-open-api project:

• https://github.com/smallrye/smallrye-open-api/tree/main/extension-jaxrs

Which must be used in an integrated environment such as Quarkus or WildFly. For example, here is the usage of it in Quakrus:

• https://quarkus.io/guides/openapi-swaggerui

The reason to use it in a container is because the container help to setup the Apis generated by the smallrye framework. For example, in microprofile-open-api test code base, here is a setup to enable it in JDK HttpServer:

• https://github.com/smallrye/smallrye-open-api/blob/main/testsuite/extra/src/test/java/test/io/smallrye/openapi/tck/ExtraSuiteTestBase.java#L123

And here is the handler in Quarkus:

• https://github.com/quarkusio/quarkus/blob/main/extensions/smallrye-openapi/runtime/src/main/java/io/quarkus/smallrye/openapi/runtime/OpenApiHandler.java#L60

For WildFly, it contains the openapi layer as described in:

• https://docs.wildfly.org/21/Galleon_Guide.html#wildfly_galleon_layers

So I added the layer in the pom.xml of this branch:

                        <layer>microprofile-openapi</layer>

#112 (comment)

However the plugin reports this error:

[ERROR] Failed to execute goal org.wildfly.plugins:wildfly-jar-maven-plugin:8.1.0.Final:package (default) on project products-runner: Provisioning failed: Failed to locate layer [model=standalone name=microprofile-openapi] in the the installation feature-pack layout -> [Help 1]

I'm not sure how to configure this properly. Could you please provide some help on this? Thanks!

[jamezp]

@liweinan I wonder if we should create a resteasy-microprofile-example. The reason this doesn't work is we're using the wildfly-ee-feature-pack and we'd need to use the full feature pack that includes the microprofile specs. Talking out loud here, I guess maybe it doesn't make sense to make a new set of examples that is separate. Keeping the examples here probably makes the most sense :)

Anyway, you need change the feature pack to org.wildfly:wildfly-galleon-pack.

[liweinan]

@jamezp Yes sir! And thanks for the help :D

[liweinan]

The setup works:

I need to split this example from bootable-jar-example into smallrye-openapi-example. In addition I need to do some cleanup.

[liweinan]

@jamezp I have finished working on the example, could you please help to review it? Thanks!

[jamezp]

In general we should not name this "smallrye-openapi". SmallRye as an Eclipse MicroProfile OpenAPI implementation. However, here we're using the MicroProfile OpenAPI.

I also question whether or not we should be using the bootable JAR here. If we just use the API's, we could run on WildFly or in other containers. This part doesn't require a change before we can merge this, but it's something we should think about IMO.

[liweinan]

@jamezp Thanks for reviewing! I'll modify the PR according to it.

[liweinan]

@jamezp I reconfigured the example to use wildfly-plugin instead of wildfly-jar-plugin. After switching the plugin, I can start the wildfly server with:

$ mvn wildfly:run
...
22:21:17,030 INFO  [org.jboss.as.server.deployment] (MSC service thread 1-5) WFLYSRV0027: Starting deployment of "smallrye-openapi-example.war" (runtime-name: "smallrye-openapi-example.war")
22:21:18,171 INFO  [org.wildfly.extension.microprofile.openapi.smallrye] (MSC service thread 1-8) WFLYMPOAI0004: Registered MicroProfile OpenAPI endpoint '/openapi' for host 'default-host'
22:21:18,392 INFO  [org.jboss.resteasy.resteasy_jaxrs.i18n] (ServerService Thread Pool -- 7) RESTEASY002225: Deploying jakarta.ws.rs.core.Application: class dev.resteasy.examples.openapi.ProductApplication
22:21:18,444 INFO  [org.hibernate.validator.internal.util.Version] (ServerService Thread Pool -- 7) HV000001: Hibernate Validator 8.0.0.Final
22:21:18,473 INFO  [org.wildfly.extension.undertow] (ServerService Thread Pool -- 7) WFLYUT0021: Registered web context: '/smallrye-openapi-example' for server 'default-server'
22:21:18,507 INFO  [org.jboss.as.server] (management-handler-thread - 1) WFLYSRV0010: Deployed "smallrye-openapi-example.war" (runtime-name : "smallrye-openapi-example.war")

And then I can access the service with:

➤ curl http://127.0.0.1:8080/openapi                                                                                                                                                                                                                                                                            22:22:00
---
openapi: 3.0.3
info:
  title: ProductApplication
  version: 1.0.0
servers:
- url: /smallrye-openapi-example
paths:
  /products:
    get:
      responses:
        default:
          description: return a list of products

However, the mvn clean install or mvn integration-test failed with:

It seems the project is not deployed:

I guess it's the plugin configuration problem, so the testing doesn't deploy the project. However I don't know how to configure it properly, could you please provide some help on this? Thanks!

[liweinan]

After reading this doc:

• http://www.mastertheboss.com/jboss-frameworks/jboss-maven/configuring-maven-wildfly-plugin/

I understand how to configure the plugin for testing. The core part is to add this line:

                            <goal>deploy</goal>

[liweinan]

@jamezp I have finished modifying the example. Could you please help to review it again? Thanks! (If it's okay I'll do squash and force push)

[jamezp]

We still need to remove the "smallrye" name as that is an implementation detail. This could just be named "openapi" or "microprofile-openapi", but it shouldn't be named "smallrye-openapi" IMO.

[liweinan]

@jamezp Thanks for review! I have finished modifications and squash the commits.