DEV Community

Cover image for Cursos que formaram meu caráter: Desenvolvimento web com Quarkus - API First com o OpenAPI Generator para APIs reativas
Arthur Fonseca
Arthur Fonseca

Posted on

Cursos que formaram meu caráter: Desenvolvimento web com Quarkus - API First com o OpenAPI Generator para APIs reativas

#gradle #openapi #quarkus #async

"Todo ato de criação é, antes de tudo, um ato de destruição" Pablo Picasso

Neste sexto post falaremos sobre geração de APIs reativas.

Esse artigo faz parte de uma série, abaixo é possível encontrar a lista completa de artigos.

Estamos nos baseando no curso Desenvolvimento web com Quarkus do @viniciusfcf.

O repositório que estamos utilizando é:

udemy / Desenvolvimento Web com Quarkus / ifood · GitLab

GitLab.com

favicon gitlab.com

OpenAPI Generator e APIs reativas

O segundo módulo ministrado por Vinícius nos apresenta problemas que a solução está mais alinhada com assincronismo.

Como estava seguindo a abordagem de API First com OpenAPI Generator para endpoints REST fui procurar se existia alguma forma de se fazer isso com o plugin.

Vi que a abordagem que estávamos utilizando era o Mutiny, e acabei caindo nessa issue que tbredzin abriu um Pull Request:

Add support for asynchronous API for JavaJaxRsSpec #10919

tbredzin avatar
tbredzin posted on

resolves #4832 This PR is an attempt at addressing https://github.com/OpenAPITools/openapi-generator/issues/4832

Motivation

Since version 2.1, JAX-RS server side component has support for returning a CompletionStage to mark the request as eligible for asynchronous processing. The advantage this approach has over the AsyncResponse based API is that it is richer and allows you to create asynchronous pipelines.

It is also extended by 3rd party libraries such as Reactor, RxJava or Mutiny. All of those allow to convert from/to CompletionStage, examples:

  • Reactor:
CompletionStage<String> single = Mono.just("something").toFuture();
CompletionStage<List<String>> many = Flux.just("something", "somethingelse")
                .collectList()
                .toFuture()
Enter fullscreen mode Exit fullscreen mode
  • RxJava3
CompletionStage<String> single = Maybe.just("something").toCompletionStage();
CompletionStage<List<String>> many = Flowable.fromArray("something", "somethingelse")
                .toList()
                .toCompletionStage();
Enter fullscreen mode Exit fullscreen mode
  • Mutiny
CompletionStage<String> single = Uni.createFrom().item("something").subscribeAsCompletionStage();
CompletionStage<List<String> many = Multi.createFrom().items("something", "somethingelse")
                .collect()
                .asList()
                .subscribeAsCompletionStage();
Enter fullscreen mode Exit fullscreen mode

Code changes

This PR adds the option supportAsync to the Java JAX-RS spec generator and updates the mustache templates.

When set to true, the generated API interfaces and classes will return CompletionStage to support running asynchronous operation in JAX-RS (supported since JAX-RS 2.1).

This option also enables java8 mode as CompletionStage requires a JDK > 1.8

Tests

Unit Tested for:

  • Generation with interfaceOnly=true with the petstore.yaml file
  • Generation with interfaceOnly=true for complex types with the ping.yaml file
  • Generation with interfaceOnly=true for primitive types with the issue_4832.yaml file
  • Generation with interfaceOnly=true and returnResponse=true with the ping.yaml file
  • Generation with interfaceOnly=false classes with ping.yaml

Sample of generated API interfaces (interfaceOnly=true):

//PingApi.java w/  returnResponse=true
CompletionStage<Response> pingGet();

// PetApi.java w/ returnResponse=false
CompletionStage<Pet> getPetById(@PathParam("petId") @ApiParam("ID of pet to return") Long petId);
CompletionStage<List<Pet>> findPetsByStatus(@QueryParam("status") @NotNull  @ApiParam("Status values that need to be considered for filter")  List<String> status);

//FakeApi.java
CompletionStage<Boolean> getBool(); //primitive type converted to class

// StoreApi.java
CompletionStage<Map<String, Integer>> getInventory();
CompletionStage<Order> placeOrder(@Valid @NotNull Order order);
CompletionStage<Void> deleteOrder(@PathParam("orderId") @ApiParam("ID of the order that needs to be deleted") String orderId);
Enter fullscreen mode Exit fullscreen mode

Sample of generated API class (interfaceOnly=false):

public CompletionStage<Response> pingGet() {
    return CompletableFuture.supplyAsync(() -> Response.ok().entity("magic!").build());
}
Enter fullscreen mode Exit fullscreen mode

Note that the current implementation from master, always returns Response. So no specific types are returned with supportAsync=true too: CompletionStage<Response>.

Project generated from it was compile successfully after running:

$ java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar generate \
-i https://raw.githubusercontent.com/OpenAPITools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml \
-g jaxrs-spec -p interfaceOnly=true,supportAsync=true -o ~/tmp

$ cd ~/tmp 
$ mvn clean package
Enter fullscreen mode Exit fullscreen mode

PR checklist

  • [x] Read the contribution guidelines.
  • [x] Pull Request title clearly describes the work in the pull request and Pull Request description provides details about how to validate the work. Missing information here may result in delayed response from the community.
  • [x] Run the following to build the project and update samples: 
    ./mvnw clean package 
./bin/generate-samples.sh
./bin/utils/export_docs_generators.sh
    Commit all changed files. This is important, as CI jobs will verify all generator outputs of your HEAD commit as it would merge with master. These must match the expectations made by your contribution. You may regenerate an individual generator by passing the relevant config(s) as an argument to the script, for example ./bin/generate-samples.sh bin/configs/java*. For Windows users, please run the script in Git BASH.
  • [x] File the PR against the correct branch: master (5.3.0), 6.0.x
  • [x] If your PR is targeting a particular programming language, @mention the technical committee members, so they are more likely to review the pull request. @nmuesch
View on GitHub

Since version 2.1, JAX-RS server side component has support for returning a CompletionStage to mark the request as eligible for asynchronous processing. The advantage this approach has over the AsyncResponse based API is that it is richer and allows you to create asynchronous pipelines.

It is also extended by 3rd party libraries such as Reactor, RxJava or Mutiny. All of those allow to convert from/to CompletionStage, examples:

Reactor

CompletionStage<String> single = Mono.just("something").toFuture();
CompletionStage<List<String>> many = Flux.just("something", "somethingelse")
                .collectList()
                .toFuture()
Enter fullscreen mode Exit fullscreen mode

RxJava3

CompletionStage<String> single = Maybe.just("something").toCompletionStage();
CompletionStage<List<String>> many = Flowable.fromArray("something", "somethingelse")
                .toList()
                .toCompletionStage();
Enter fullscreen mode Exit fullscreen mode

Mutiny

CompletionStage<String> single = Uni.createFrom().item("something").subscribeAsCompletionStage();
CompletionStage<List<String> many = Multi.createFrom().items("something", "somethingelse")
                .collect()
                .asList()
                .subscribeAsCompletionStage();
Enter fullscreen mode Exit fullscreen mode

Pensei, porque não? Vamos ver no que isso vai dar...

Podemos ver a configuração utilizando API-First em nosso projeto nos arquivos applications/marketplace/build.gradle:

apply from: "$rootDir/plugins/openapigen_marketplace.gradle"
Enter fullscreen mode Exit fullscreen mode

E no arquivo plugins/openapigen_marketplace.gradle:

import org.openapitools.generator.gradle.plugin.tasks.GenerateTask

buildscript {
    repositories {
        mavenLocal()
        maven { url "https://repo1.maven.org/maven2" }
    }
    dependencies {
        classpath "org.openapitools:openapi-generator-gradle-plugin:$openApiGenVersion"
    }
}

apply plugin: 'org.openapi.generator'

def apiServerOutput = "$buildDir/generated/openapi-code-server".toString()

task generatePratosApiServer(type: GenerateTask) {
    generatorName = "jaxrs-spec"
    inputSpec = "$projectDir/src/main/resources/openapi/pratos_v1.yml".toString()
    outputDir = apiServerOutput
    apiPackage = "org.openapi.server.v1.pratos.api"
    invokerPackage = "org.openapi.v1.pratos.invoker"
    modelPackage = "org.openapi.v1.pratos.model"
    configOptions = [
        "dateLibrary"            : "java8",
        "hideGenerationTimestamp": "true",
        "interfaceOnly"          : "true",
        "supportAsync"           : "true",
        "useOptional"            : "true",
        "useBeanValidation"      : "false",
        "useSwaggerAnnotations"  : "false"
    ]
}

task generateRestaurantesApiServer(type: GenerateTask) {
    generatorName = "jaxrs-spec"
    inputSpec = "$projectDir/src/main/resources/openapi/restaurantes_v1.yml".toString()
    outputDir = apiServerOutput
    apiPackage = "org.openapi.server.v1.restaurantes.api"
    invokerPackage = "org.openapi.v1.restaurantes.invoker"
    modelPackage = "org.openapi.v1.restaurantes.model"
    configOptions = [
        "dateLibrary"            : "java8",
        "hideGenerationTimestamp": "true",
        "interfaceOnly"          : "true",
        "supportAsync"           : "true",
        "useOptional"            : "true",
        "useBeanValidation"      : "false",
        "useSwaggerAnnotations"  : "false"
    ]
}

compileJava.dependsOn(
    generatePratosApiServer, generateRestaurantesApiServer
)

sourceSets.main.java.srcDir "$apiServerOutput/src/gen/java"
Enter fullscreen mode Exit fullscreen mode

No post anterior explicamos várias dessas configurações, o que ficou faltando foi só a supportAsync que como o próprio nome já diz, habilita ou não o suporte a APIs assíncronas.

Nesse projeto também optei por criar 2 APIs para a geração, uma para pratos ("$projectDir/src/main/resources/openapi/pratos_v1.yml".toString()) e outra para restaurantes ("$projectDir/src/main/resources/openapi/restaurantes_v1.yml".toString()).

Quando executamos a fase compileJava ou tasks que dependem dela podemos ver que a seguinte estrutura foi criada em applications/marketplace/build:

Generated source

Analisando as classes geradas, temos PratoAPI:

package org.openapi.server.v1.pratos.api;

import org.openapi.v1.pratos.model.Prato;
import javax.ws.rs.*;
import javax.ws.rs.core.Response;
import java.util.concurrent.CompletionStage;
import java.util.concurrent.CompletableFuture;
import java.io.InputStream;
import java.util.Map;
import java.util.List;

@Path("/pratos")
@javax.annotation.Generated(value = "org.openapitools.codegen.languages.JavaJAXRSSpecServerCodegen")
public interface PratosApi {

    @GET
    @Produces({ "application/json" })
    CompletionStage<List<Prato>> recuperaPratosRestaurante();
}
Enter fullscreen mode Exit fullscreen mode

E RestaurantesAPI:

package org.openapi.server.v1.restaurantes.api;

import org.openapi.v1.restaurantes.model.Prato;
import javax.ws.rs.*;
import javax.ws.rs.core.Response;
import java.util.concurrent.CompletionStage;
import java.util.concurrent.CompletableFuture;
import java.io.InputStream;
import java.util.Map;
import java.util.List;


@Path("/restaurantes/{idRestaurante}/pratos")
@javax.annotation.Generated(value = "org.openapitools.codegen.languages.JavaJAXRSSpecServerCodegen")
public interface RestaurantesApi {

    @GET
    @Produces({ "application/json" })
    CompletionStage<List<Prato>> recuperaPratosRestaurante(@PathParam("idRestaurante") Long idRestaurante);
}
Enter fullscreen mode Exit fullscreen mode

E seguindo com a nossa configuração, precisamos implementar um classe concreta para definir como o método vai funcionar:

applications/marketplace/src/main/java/com/gitlab/arthurfnsc/ifood/marketplace/PratoResource:

package com.gitlab.arthurfnsc.ifood.marketplace;

import io.smallrye.mutiny.Multi;
import java.util.List;
import java.util.concurrent.CompletionStage;
import javax.ws.rs.Consumes;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;
import org.openapi.server.v1.pratos.api.PratosApi;
import org.openapi.v1.pratos.model.Prato;

@Path("/pratos")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class PratoResource implements PratosApi {

    @Override
    public CompletionStage<List<Prato>> recuperaPratosRestaurante() {
        Multi<Prato> pratos = com.gitlab.arthurfnsc.ifood.marketplace.Prato.recuperaPratosApi();
        return pratos.collect().asList().subscribeAsCompletionStage();
    }
}
Enter fullscreen mode Exit fullscreen mode

applications/marketplace/src/main/java/com/gitlab/arthurfnsc/ifood/marketplace/RestauranteResource:

package com.gitlab.arthurfnsc.ifood.marketplace;

import io.smallrye.mutiny.Multi;
import java.util.List;
import java.util.concurrent.CompletionStage;
import javax.ws.rs.Consumes;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;
import org.openapi.server.v1.restaurantes.api.RestaurantesApi;

@Path("/restaurantes")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class RestauranteResource implements RestaurantesApi {

    @Override
    public CompletionStage<List<org.openapi.v1.restaurantes.model.Prato>> recuperaPratosRestaurante(
        Long idRestaurante
    ) {
        Multi<org.openapi.v1.restaurantes.model.Prato> pratos = com.gitlab.arthurfnsc.ifood.marketplace.Prato.recuperaPratosApi(
            idRestaurante
        );
        return pratos.collect().asList().subscribeAsCompletionStage();
    }
}
Enter fullscreen mode Exit fullscreen mode

Na classe Prato, no mesmo pacote do nosso resource implementamos os seguintes métodos:

package com.gitlab.arthurfnsc.ifood.marketplace;

...

public class Prato extends PanacheEntityBase {

    ...
    public static Multi<org.openapi.v1.pratos.model.Prato> recuperaPratosApi() {
        return findAll()
            .stream()
            .map(p -> (Prato) p)
            .onItem()
            .transform(PratoMapper::paraPratoApi);
    }

    public static Multi<org.openapi.v1.restaurantes.model.Prato> recuperaPratosApi(
        Long idRestaurante
    ) {
        return find("restaurante.id", idRestaurante)
            .stream()
            .map(p -> (Prato) p)
            .onItem()
            .transform(PratoMapper::paraPratoRestauranteApi);
    }
    ...
}
Enter fullscreen mode Exit fullscreen mode

Essa minha abordagem de ter 2 OpenAPIs gerou um problema que pode ser percebido no código acima. Vocês podem percebem que acabaram sendo geradas 2 classes Prato, uma em org.openapi.v1.pratos.model.Prato e outra em org.openapi.v1.restaurantes.model.Prato o que me deixou 2 métodos muito parecidos, com uma diferença do método de transformação chamado.

No caso da solução do Vinícius as Resources dele retornam Multi:

package com.github.viniciusfcf.ifood.mp;

...
import io.smallrye.mutiny.Multi;

public class PratoResource {

    @Inject
    PgPool pgPool;

    @GET
    @APIResponse(responseCode = "200", content = @Content(schema = @Schema(type = SchemaType.ARRAY, implementation = PratoDTO.class)))
    public Multi<PratoDTO> buscarPratos() {
        return Prato.findAll(pgPool);
    }
}
Enter fullscreen mode Exit fullscreen mode 
package com.github.viniciusfcf.ifood.mp;

...
import io.smallrye.mutiny.Multi;

public class RestauranteResource {

    @Inject
    PgPool client;

    @GET
    @Path("{idRestaurante}/pratos")
    public Multi<PratoDTO> buscarPratos(@PathParam("idRestaurante") Long idRestaurante) {
        return Prato.findAll(client, idRestaurante);
    }
}
Enter fullscreen mode Exit fullscreen mode

Como estamos trabalhando com CompletionStage ao invés de Multi, vamos ver se aquela dica do tbredzin funciona:

PratoResource

    @Override
    public CompletionStage<List<Prato>> recuperaPratosRestaurante() {
        Multi<Prato> pratos = com.gitlab.arthurfnsc.ifood.marketplace.Prato.recuperaPratosApi();
        return pratos
            .collect()
            .asList()
            .subscribeAsCompletionStage();
    }
Enter fullscreen mode Exit fullscreen mode

RestauranteResource

    @Override
    public CompletionStage<List<org.openapi.v1.restaurantes.model.Prato>> recuperaPratosRestaurante(
        Long idRestaurante
    ) {
        Multi<org.openapi.v1.restaurantes.model.Prato> pratos = com.gitlab.arthurfnsc.ifood.marketplace.Prato.recuperaPratosApi(
            idRestaurante
        );
        return pratos
            .collect()
            .asList()
            .subscribeAsCompletionStage();
    }
Enter fullscreen mode Exit fullscreen mode

Happy Celebration GIF by Manchester United - Find & Share on GIPHY

Discover & share this Manchester United GIF with everyone you know. GIPHY is how you search, share, discover, and create GIFs.

favicon giphy.com

Você pode ter percebido que não interagimos com o PgPool como o Vinícius. Isso se deve ao fato de conseguirmos usar o hibernate em uma solução reativa, o que ainda estava em fase beta quando o Vinícius fez o curso dele. Falaremos mais sobre o quarkus-hibernate-reactive-panache adiante.

Considerações finais

Quando estava fazendo essa abordagem fiquei com dúvida se essa era uma boa implementação. Afinal, qual a diferença entre um Multi ou Uni e um CompletionStage? O seguinte link me ajudou um pouco a entender que eles não são a mesma coisa:

smallrye.io

While CompletionStage and CompletableFuture are close to Uni in terms of use case, there are some fundamental differences.

CompletionStage are eager. When a method returns a CompletionStage, the operation has already been triggered. The outcome is used to complete the returned CompletionStage. On the other side, Unis are lazy. The operation is only triggered once there is a subscription.

CompletionStage caches the outcome. So, once received, you can retrieve the result. Every retrieval will get the same result. With Uni, every subscription has the opportunity to re-trigger the operation and gets a different result.

Segue também um outro link bem interessante:

smallrye.io

Sobre a utilização de OpenAPI Gen para APIs reativas

Bem, essa foi a primeira implementação que fiz, e portanto não consegui abstrair maiores problemas. Como não estressei a solução em vários projetos, não seria algo que eu colocaria em produção em um cliente. Ao meu modo de ver, é importante validar outros cenários mais complexos.

Mas achei bem interessante essa possibilidade do plugin.

No próximo post falaremos sobre uma solução da OWASP para validação de vulnerabilidade em nossas bibliotecas.

Esse post faz parte de uma série sobre Cursos que formaram meu caráter: Desenvolvimento web com Quarkus.

A série completa é:

Top comments (0)

Read next

bump_sh profile image

OpenAPI 3.1 - The Cheat Sheet

Bump.sh -

tomekbuszewski profile image

How to Add OpenAPI to your Express App?

Tomasz Buszewski -

jonasbn profile image

Hosting Swagger-UI using GitHub Pages

Jonas Brømsø -

brysontyrrell profile image

Using the Swift OpenAPI Generator for the Jamf Pro API

Bryson Tyrrell -