Cursos que formaram meu caráter: Desenvolvimento web com Quarkus — API First com o OpenAPI Generator para APIs reativas
“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 Vinicius Ferraz Campos Florentino.
O repositório que estamos utilizando é:
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:
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()RxJava3
CompletionStage<String> single = Maybe.just("something").toCompletionStage();
CompletionStage<List<String>> many = Flowable.fromArray("something", "somethingelse")
.toList()
.toCompletionStage();Mutiny
CompletionStage<String> single = Uni.createFrom().item("something").subscribeAsCompletionStage();
CompletionStage<List<String> many = Multi.createFrom().items("something", "somethingelse")
.collect()
.asList()
.subscribeAsCompletionStage();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"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"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:
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();
}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);
}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();
}
}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();
}
}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);
}
...
}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);
}
}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);
}
}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();
}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();
}
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:
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:
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 é:
- Talk is cheap show me the code
- Utilizando Gradle ao invés de Maven
- Plugins do Gradle: Gerenciador de versões de bibliotecas com Versions
- Plugins do Gradle: Saudades do Maven, relatórios com Project-report
- Plugins do Gradle: API First com o OpenAPI Generator
- Plugins do Gradle: API First com o OpenAPI Generator para APIs reativas
- Plugins do Gradle: Validação de vulnerabilidades de dependências com OWASP Dependency Check [não publicado]
- Plugins do Gradle: Lint com Spotless [não publicado]
- GitLab: Motivação para a escolha [não publicado]
- GitLab: Considerações sobre o Prettier em pipelines [não publicado]
- Gitmoji [não publicado]
- SDK Man [não publicado]
- Pré commit hook [não publicado]
- application.yml: Utilizando YML em propriedades de aplicação [não publicado]
- application.yml: Utilizando variáveis de ambiente [não publicado]
- application.yml: Sobrescrevendo opções em teste [não publicado]
- Mapstruct: Utilizando expressões para mapeamentos [não publicado]
- Microprofile SecurityScheme: Sobrescrevendo tokenUrl [não publicado]
- Prometheus: O problema simples que me custou algumas horas [não publicado]
- quarkus-hibernate-reactive-panache: Utilizando as vantagens do Hibernate em projetos reativos [não publicado]
- Testcontainers: Configuração para projetos reativos [não publicado]
Original post published at https://dev.to on December 17th, 2022.
