How can I generate Quarkus rest JX-RS service based on given openapi 3.0.3 yaml file

Question

Currently I am developing an application using quarkus. I have an openapi yaml file that describes everything. I wanted to know if there are quarkus extensions or tool with which I can generate the rest end points that would produce and consume same file format.

Pisgah

Answer 1

As long as you dont need any Quarkus specific features(e.g reactive, @Cached,..), then the REST endpoints are standard JAXRS endpoints and you can use the openapi generator to generate the interfaces and model POJOs for you. After that you simply implement the generated interface:

openapi-cli generate -i url_or_path_to_your_api_schema.yml -g jaxrs-spec --skip-validate-spec --additional-properties=interfaceOnly=true,useSwaggerAnnotations=false

The above command will generate only JAXRS endpoint interface any POJO classes for any models defined in API. You can copy them to your project and implement the iface.

Instead of manual cli invocation, you could integrate this in your maven build, using the openapi generator plugin:

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
       <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/yourapi.yaml</inputSpec>
                <generatorName>jaxrs-spec</generatorName>
                <additionalProperties>interfaceOnly=true,useSwaggerAnnotations=false</additionalProperties>
                <configOptions>
                   <sourceFolder>src/gen/java/main</sourceFolder>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

There is also a complete project stub generator for Quarkus if thats something you fancy: (as --library=quarkus option for jaxrs-spec generator)

There are many more options you may wish to configure described in the docs of OpenApi generators. You can also customize the code templates(moustache) in case the built in ones miss sth you need, though at that point you might look into creating your own generator.

If you need a client and you are ok with the standard Microprofile REST client approach, then the Openapi generator will also work fine:

openapi-cli generate -i path_to_your_openapi_schema.yml -g java --library microprofile

The OpenApi generator is a complex project and not without issues, so it would be best if Quarkus community adopted a custom optimized tooling for server and client code generators, to fully utilise all features e.g. reactive client...

Megdal

May I use swagger code generator instead of jaxrs-spec. BTW I used the above pom and it could not generate the java interfaces on build time :( – Pisgah

what do you mean by "may I use swagger code generator instead of jaxrs"? codegen is a tool that generates client or server code based on schema. The two most popular ones are openapitools(linked above) and github.com/swagger-api/swagger-codegen. You can use either to generate a perfectly valid client/server stubs in many frameworks( ok okhttp, cxf, resteasy...). ATM the openapi generator is more active, supports MicroProfile rest clients, etc. The plugin works fine - have a look at working sample here github.com/yntelectual/quarkus-openapi which uses the swagger petstore sample – Megdal

Answer 2

We are currently working on an official OpenAPI Generator extension: https://github.com/quarkiverse/quarkus-openapi-generator#readme

Please take a look if you're interested. We'd love to hear feedback from the community.

Essential

OP asked for server resource generation, the plugin you're working on/linked to generates clients (works well btw, thanks!) – Amarillo

See here: github.com/quarkiverse/quarkus-openapi-generator/pull/482 :D – Essential

Answer 3

Currently, there is no offical extension / tools inside Quarkus to generate JAX-RS stubs from an OpenAPI file.

However, this has been discussed on the Quarkus dev mailing list, you can have a look and provide feedback on it: https://groups.google.com/g/quarkus-dev/c/f8hJRm8oWbQ/m/UW_kQ7UEAwAJ

Note that there is an OpenAPI generator for JAX-RS, you may be able to use it to generate a JAX-RS compliant endpoint that would works with only small modifications in Quarkus: https://openapi-generator.tech/docs/generators/jaxrs-spec

Baluchistan

Answer 4

This is a quirky issue (pun intended) to say the least. For me what worked for Quarkus (platform version 3.2.3, Java 17, GraalVM, Jakarta EE) using the jaxrs-spec generator was the openapi-generator-maven-plugin version 6.4.0:

<plugin>
        <groupId>org.openapitools</groupId>
        <artifactId>openapi-generator-maven-plugin</artifactId>
        <version>6.4.0</version>
        <executions>
          <execution>
            <goals>
              <goal>generate</goal>
            </goals>
            <configuration>
              <inputSpec>${project.basedir}/src/main/resources/META-INF/openapi.yml</inputSpec>
              <generatorName>jaxrs-spec</generatorName>
              <additionalProperties>interfaceOnly=true,useSwaggerAnnotations=false,returnResponse=true</additionalProperties>
              <configOptions>
                <library>quarkus</library>
                <sourceFolder>src/gen/java/main</sourceFolder>
              </configOptions>
              <configurationFile>${project.basedir}/src/main/resources/META-INF/config.json</configurationFile>
            </configuration>
          </execution>
        </executions>
      </plugin>

With additional configurations in file config.json:

{
  "dateLibrary": "java8",
  "useJakartaEe": true,
  "hideGenerationTimestamp": true,
  "modelPackage": "com.model",
  "apiPackage": "com.model.rest",
  "invokerPackage": "com.model.rest",
  "serializableModel": true,
  "useTags": true,
  "useGzipFeature": true,
  "interfaceOnly": true,
  "java17" : true
}

Squatness

did you find that when you used the openapi generator plugin but then enable live (resume) testing in quarkus that it at times generates jax-rs instead of jakarta artifacts? I am running into this - it doesnt seem like quarkus does jakarta by default (I'd think now a days it would) – Fordone