Quarkus: Offer API generation based on OpenAPI definition

[emmanuelbernard]

There is a maven plugin that takes the OpenAPI definition and generates the JAX-RS endpoints and keep them in sync
https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator-maven-plugin

A attendee was wondering if our generator (code.*, CLI) was able to add this maven plugin (option).

I guess that's something we could do once extensions can control project generation.

[emmanuelbernard]

cc @ia3andy

[ia3andy]

Behind, it uses:

<dependency>
            <groupId>org.openapitools</groupId>
            <artifactId>openapi-generator</artifactId>
            <version>${project.version}</version>
 </dependency>

Which is plain Java, maybe it would be easier to just integrate it as part of the Quarkus codegen. We should also look if it works with Quarkus native (for Code Quarkus).

[kenfinnigan]

I'd be curious to see if instead there was a piece of Apicurio we could include for that generation?

@EricWittmann thoughts?

[EricWittmann]

I do have some code in Apicurio for this, and it might work better than the openapi-generator tool for JAX-RS. It would be very interesting if someone were to do a comparison of the results. The Apicurio code can be found here:

https://github.com/Apicurio/apicurio-studio/tree/master/back-end/hub-codegen

It is integrated into the Apicurio Studio upstream project, so you could test it out easily using https://studio.apicur.io - but there is no maven plugin or anything like that.

All of that said, the openapi-generator project is very popular and I assume does a reasonable job...

[kenfinnigan]

A related idea I'd had for Thorntail a while back was a way to "link" methods in an OpenAPI doc to Java class and method, maybe with a custom property in the doc, and have the code just "know" how to link the two and what to execute

[misl]

Thanks @kenfinnigan for pointing me to this issue.

Swagger for example already has Swagger Inflector. And the other day I discovered Vert.x Web API Service. This together with Quarkus seems like an ideal development stack to me. Although I wonder what plumbing it takes to get this working.

It seems like it might even be possible to do this with hardly any code generation.

[misl]

BTW If we could not only target OpenAPI but AsyncAPI as well that would be even better. :-)

[EricWittmann]

There is a smallrye project for asyncapi here: https://github.com/smallrye/smallrye-async-api/

Not too much there yet, but it's a place to explore ideas.

[dhartford]

The spec file generated by smallrye/quarkus -- I'm not sure how to have the spec file available for the openapigenerator maven plugin, any advice (I tried application.properties mp.openapi.scan.disable=true without any success)?

I see it in the final *-runner.jar, but it isn't in any of the /target/ locations during maven build phases:

META-INF/resources/quarkus-generated-openapi-doc.YAML

[kenfinnigan]

If you're looking to pass a file to Quarkus to represent the OpenAPI document, it needs to be in META-INF/openapi.yaml

[dhartford]

Actually, it looks like the openapi tools can pull the spec file from inside a jar file. A completely raw workaround to pivot from (using openapi maven plugin):

           <!-- client sdk generation of OpenAPI endpoints -->
            <plugin>
                <groupId>org.openapitools</groupId>
                <artifactId>openapi-generator-maven-plugin</artifactId>
                <version>4.1.1</version>
                <executions>
                    <execution>
                        <phase>package</phase>
                        <goals>
                            <goal>generate</goal>
                        </goals>
                        <configuration>
                            <inputSpec>META-INF/resources/quarkus-generated-openapi-doc.YAML</inputSpec>
                            <generatorName>javascript</generatorName>
                        </configuration>
                    </execution>
                </executions>
                <dependencies>
                    <dependency>
                        <groupId>quarkus</groupId>
                        <artifactId>quarkus-app</artifactId>
                        <version>1.0</version>
                        <scope>system</scope>
                        <systemPath>${basedir}/target/${artifactId}-${version}-runner.jar</systemPath>
                    </dependency>
                </dependencies>
            </plugin>

[stale[bot]]

This issue/pullrequest has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[dudash]

+1

The API first approach here would be a really nice way to use Quarkus:
https://developers.redhat.com/blog/2019/01/14/building-a-node-js-service-using-the-api-first-approach/

Right now I'm in the process of building a new CRUD API service. I defined it using Apicurio and then I bootstrapped a Quarkus service (with Smallrye-OpenAPI and MongoDB-w-Panache). Now I'm adding the code based on my API. But it would be nicer if it was generated for me. It would also be nice to have validator type checks like oas-tools does.

[ahofmeister]

This would indeed very, very nice to have! :)

[agilob]

To use openapi code generation, project must also include external dependencies for JSON serialisation, http client, date formatting etc. OpenAPI can be customized to select which date formatter, and template is used.

For example, these are currently allowed libraries/templates supported:
jersey1
feign
jersey2
okhttp-gson
retrofit
retrofit2
resttemplate
resteasy
vertx
google-api-client

https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator-maven-plugin/README.md#general-configuration-parameters

You can see here, to use them users still need to add dependencies for GSON, fireGSON, OkHTTP, retrofit, more and more and more. I think ideally openapi generation would include templates for Quarkus, instead Quarkus for OpenAPI (the way Vertx is added). This would allow us, users, to use OpenAPI generation in Quarkus without adding 3rd party dependencies, duplicating JSON serializers and keep project clean with Quarkus managed dependencies and code.

Maven configuration would look like this:

      <plugin>
        <groupId>org.openapitools</groupId>
        <artifactId>openapi-generator-maven-plugin</artifactId>
        <executions>
          <execution>
              <goals>
                <goal>generate</goal>
              </goals>
              <configuration>
                  <inputSpec>src/main/resources/META-INF/openapi.yaml</inputSpec>
                  <output>${project.build.directory}/generated-sources</output>
                  <language>java</language>
                  <modelPackage>net.agilob.model</modelPackage>
                  <generateApis>true</generateApis>
                  <generateApiTests>true</generateApiTests>
                  <apiPackage>net.agilob.api</apiPackage>
                  <configOptions>
                    <sourceFolder>src/java/main</sourceFolder>
                    <library>quarkus</library>
                  </configOptions>
              </configuration>
          </execution>
        </executions>
      </plugin>

[pratikmallya]

This would be really nice to have! I was able to use the JAX-RS resteasy code generator to get an interface, and use that to build a quarkus web service. However, a code generator that would spin up a quarkus service directly would be very useful, and contribute to the adoption of Quarkus.

[pratikmallya]

You can see here, to use them users still need to add dependencies for GSON, fireGSON, OkHTTP, retrofit, more and more and more.

Yes, the _generation_ itself may require those dependencies, but the _generated_ Quarkus code would not! The way this works is that the openapi definitions may be centralized somewhere, and the openapi-generator is used to create server stubs for multiple frameworks.

[vietk]

Hello, we are using the approach described by @emmanuelbernard using the openapi-generator-maven-plugin.
However the generator is not compatible with asynchronous operation, so we are still defining our async endpoint "by hand"

For reference : https://github.com/OpenAPITools/openapi-generator/issues/4832

Regards

[andrejpetras]

Hi,
I created mp-rest-client-maven-plugin few moths ago. It wraps the swagger-codegen and generate Microprofile Rest-Client classes.
Source code: https://github.com/lorislab/mp-rest-client-maven-plugin