Arquitetura orientada a eventos: geração automática de DTO a partir da documentação do evento

Uma coisa muito importante no processo de desenvolvimento de software que muitas vezes é negligenciada nos estágios iniciais de um projeto é a documentação da API. Uma das soluções para esse problema são os frameworks para geração automática de documentação.

No caso da divisão do projeto em microsserviços e utilização da arquitetura Event-Driven, a interação entre os serviços é construída a partir de eventos transmitidos pelo message broker.

Para gerar documentação no caso de uma arquitetura orientada a eventos, existe AsyncApi . AsyncAPI é uma iniciativa de código aberto que busca melhorar o estado atual da Event-Driven Architecture (EDA). AsyncApi possui várias ferramentas Java que permitem gerar documentação a partir do código. Neste artigo , descrevi como configurar uma dessas ferramentas springwolf .

Neste artigo, gostaria de contar como resolvi a seguinte tarefa, ou seja, a geração de DTOs usando a documentação JSON que o springwolf gera.

Problema

A estrutura de documentação gerada pelo spring wolf se parece com isto:

 { "service": { "serviceVersion": "2.0.0", "info": { //block with service info }, "servers": { "kafka": { //describe of kafka connection } }, "channels": { "kafka-channel": { "subscribe": { //... "message": { "oneOf": [ { "name": "pckg.test.TestEvent", "title": "TestEvent", "payload": { "$ref": "#/components/schemas/TestEvent" } } ] } }, //... } }, "components": { "schemas": { "TestEvent": { //jsonschema of component } } } } }

Como jsonschema é usado para descrever os componentes na documentação, decidi usar a biblioteca jsonschema2pojo para resolver esse problema. No entanto, no processo de tentar implementar meu plano, encontrei vários problemas:

• você precisa analisar adicionalmente o documento JSON para extrair objetos que descrevem os componentes. Como jsonschema2pojo recebe objetos jsonschema como entrada, eles estão no bloco de componentes.
• jsonschema2pojo não funciona bem com polimorfismo e não lida com referências padrão do bloco oneOf que estão em AsyncAPI. A descrição da herança requer campos especiais no esquema (extends.javaType), que não podem ser adicionados à documentação do AsyncAPI simplesmente.
• como as classes geradas em nosso caso devem ser usadas para desserializar mensagens do broker, é necessário adicionar anotações de Jackson descrevendo descritores e subtipos.

Todos esses problemas me levaram à necessidade de implementar meu wrapper sobre jsonschema2pojo, que irá extrair as informações necessárias da documentação, suportar polimorfismo e adicionar anotações de Jackson. O resultado é um plug-in Gradle com o qual você pode gerar classes DTO para seu projeto usando a API springwolf. A seguir, tentarei demonstrar como anotar classes para documentação e como usar o plugin Springwolfdoc2dto .

Configuração da documentação

Aqui eu gostaria de considerar os detalhes de quando a geração de tipos não primitivos, como Enum e Map. E também descrever as ações necessárias para o polimorfismo.

Vejamos a seguinte mensagem:

 @Getter @Setter @NoArgsConstructor @AllArgsConstructor public class TestEvent implements Serializable { private String id; private LocalDateTime occuredOn; private TestEvent.ValueType valueType; private Map<String, Boolean> flags; private String value; public enum ValueType { STRING("STRING"), BOOLEAN("BOOLEAN"), INTEGER("INTEGER"), DOUBLE("DOUBLE"); private final String value; public ValueType(String value) { this.value = value; } } }

O jsonschema para tal mensagem ficaria assim:

 { "service": { //... "components": { "schemas": { "TestEvent": { "type": "object", "properties": { "id": { "type": "string", "exampleSetFlag": false }, "occuredOn": { "type": "string", "format": "date-time", "exampleSetFlag": false }, "valueType": { "type": "string", "exampleSetFlag": false, "enum": [ "STRING", "BOOLEAN", "INTEGER", "DOUBLE" ] }, "flags": { "type": "object", "additionalProperties": { "type": "boolean", "exampleSetFlag": false }, "exampleSetFlag": false }, "value": { "type": "string", "exampleSetFlag": false } }, "example": { "id": "string", "occuredOn": "2015-07-20T15:49:04", "valueType": "STRING", "flags": { "additionalProp1": true, "additionalProp2": true, "additionalProp3": true } }, "exampleSetFlag": true } } } } }

Ao gerar classes DTO, obteremos a seguinte estrutura de classe. Você pode ver que Enum é processado como na versão original, no entanto, a coleção do tipo Map<String, Boolean> se transformou em uma classe separada Flags e todo o valor da coleção em si cairá no campo Flags.additionalProperties .

 package pckg.test; // import @JsonInclude(JsonInclude.Include.NON_NULL) @JsonPropertyOrder({ "id", "occuredOn", "valueType", "flags", "value" }) @Generated("jsonschema2pojo") public class TestEvent implements Serializable { @JsonProperty("id") private String id; @JsonProperty("occuredOn") private LocalDateTime occuredOn; @JsonProperty("valueType") private TestEvent.ValueType valueType; @JsonProperty("flags") private Flags flags; @JsonProperty("value") private String value; @JsonIgnore private Map<String, Object> additionalProperties = new LinkedHashMap<String, Object>(); private final static long serialVersionUID = 7311052418845777748L; // Getters ans Setters @Generated("jsonschema2pojo") public enum ValueType { STRING("STRING"), BOOLEAN("BOOLEAN"), INTEGER("INTEGER"), DOUBLE("DOUBLE"); private final String value; private final static Map<String, TestEvent.ValueType> CONSTANTS = new HashMap<String, TestEvent.ValueType>(); static { for (TestEvent.ValueType c: values()) { CONSTANTS.put(c.value, c); } } ValueType(String value) { this.value = value; } @Override public String toString() { return this.value; } @JsonValue public String value() { return this.value; } @JsonCreator public static TestEvent.ValueType fromValue(String value) { TestEvent.ValueType constant = CONSTANTS.get(value); if (constant == null) { throw new IllegalArgumentException(value); } else { return constant; } } } } @JsonInclude(JsonInclude.Include.NON_NULL) @JsonPropertyOrder({ }) @Generated("jsonschema2pojo") public class Flags implements Serializable { @JsonIgnore private Map<String, Boolean> additionalProperties = new LinkedHashMap<String, Boolean>(); private final static long serialVersionUID = 7471055390730117740L; //getters and setters }

Polimorfismo

E agora vamos ver como fornecer uma opção de polimorfismo. Isso é relevante quando queremos enviar vários subtipos de mensagens para um tópico do broker e implementar nosso ouvinte para cada subtipo.

Para fazer isso, precisamos adicionar uma classe pai à lista de provedores e adicionar a anotação @Schema do swagger a ela.

 @NoArgsConstructor(access = AccessLevel.PROTECTED) @AllArgsConstructor @Getter @Setter(AccessLevel.PROTECTED) @EqualsAndHashCode @JsonTypeInfo( use = JsonTypeInfo.Id.NAME, include = JsonTypeInfo.As.EXISTING_PROPERTY, property = "type", visible = true, defaultImpl = ChangedEvent.class ) @JsonSubTypes(value = { @JsonSubTypes.Type(name = ChangedEvent.type, value = ChangedEvent.class), @JsonSubTypes.Type(name = DeletedEvent.type, value = DeletedEvent.class) }) @JsonIgnoreProperties(ignoreUnknown = true) @Schema(oneOf = {ChangedEvent.class, DeletedEvent.class}, discriminatorProperty = "type", discriminatorMapping = { @DiscriminatorMapping(value = ChangedEvent.type, schema = ChangedEvent.class), @DiscriminatorMapping(value = DeletedEvent.type, schema = DeletedEvent.class), }) public abstract class DomainEvent { @Schema(required = true, nullable = false) private String id; @JsonSerialize(using = LocalDateTimeSerializer.class) @JsonDeserialize(using = LocalDateTimeDeserializer.class) @JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd HH:mm:ss") private LocalDateTime occuredOn = LocalDateTime.now(); public abstract String getType(); } /** * Subtype ChangedEvent */ public class ChangedEvent extends DomainEvent implements Serializable { public static final String type = "CHANGED_EVENT"; private String valueId; private String value; } /** * Subtype DeletedEvent */ public class DeletedEvent extends DomainEvent implements Serializable { public static final String type = "DELETED_EVENT"; private String valueId; }

Nesse caso, a descrição dos componentes na documentação será alterada da seguinte forma:

 "components": { "schemas": { "ChangedEvent": { "type": "object", "properties": { "id": { "type": "string", "exampleSetFlag": false }, "occuredOn": { "type": "string", "format": "date-time", "exampleSetFlag": false }, "value": { "type": "string", "exampleSetFlag": false }, "valueId": { "type": "string", "exampleSetFlag": false }, "type": { "type": "string", "exampleSetFlag": false } }, "example": { "id": "string", "occuredOn": "2015-07-20T15:49:04", "value": "string", "valueId": "string", "type": "CHANGED_EVENT" }, "exampleSetFlag": true }, "DeletedEvent": { "type": "object", "properties": { "id": { "type": "string", "exampleSetFlag": false }, "occuredOn": { "type": "string", "format": "date-time", "exampleSetFlag": false }, "valueId": { "type": "string", "exampleSetFlag": false }, "type": { "type": "string", "exampleSetFlag": false } }, "example": { "id": "string", "occuredOn": "2015-07-20T15:49:04", "valueId": "string", "type": "DELETED_EVENT" }, "exampleSetFlag": true }, "DomainEvent": { "type": "object", "properties": { "id": { "type": "string", "exampleSetFlag": false }, "occuredOn": { "type": "string", "format": "date-time", "exampleSetFlag": false }, "type": { "type": "string", "exampleSetFlag": false } }, "example": { "id": "string", "occuredOn": "2015-07-20T15:49:04", "type": "string" }, "discriminator": { "propertyName": "type", "mapping": { "CHANGED_EVENT": "#/components/schemas/ChangedEvent", "DELETED_EVENT": "#/components/schemas/DeletedEvent" } }, "exampleSetFlag": true, "oneOf": [ { "$ref": "#/components/schemas/ChangedEvent", "exampleSetFlag": false }, { "$ref": "#/components/schemas/DeletedEvent", "exampleSetFlag": false } ] } } }

Depois disso, o plug-in levará em consideração os links do bloco oneOf e os discriminadores descritos. Como resultado, obtemos a seguinte estrutura de classes.

 package pckg.test; // import @JsonInclude(JsonInclude.Include.NON_NULL) @JsonPropertyOrder({ "id", "occuredOn", "type" }) @Generated("jsonschema2pojo") @JsonTypeInfo(property = "type", use = JsonTypeInfo.Id.NAME, include = JsonTypeInfo.As.EXISTING_PROPERTY, visible = true) @JsonSubTypes({ @JsonSubTypes.Type(name = "CHANGED_EVENT", value = ChangedEvent.class), @JsonSubTypes.Type(name = "DELETED_EVENT", value = DeletedEvent.class) }) public class DomainEvent implements Serializable { @JsonProperty("id") protected String id; @JsonProperty("occuredOn") protected LocalDateTime occuredOn; @JsonProperty("type") protected String type; @JsonIgnore protected Map<String, Object> additionalProperties = new LinkedHashMap<String, Object>(); protected final static long serialVersionUID = 4691666114019791903L; //getters and setters } // import @JsonInclude(JsonInclude.Include.NON_NULL) @JsonPropertyOrder({ "id", "occuredOn", "valueId", "type" }) @Generated("jsonschema2pojo") public class DeletedEvent extends DomainEvent implements Serializable { @JsonProperty("id") private String id; @JsonProperty("occuredOn") private LocalDateTime occuredOn; @JsonProperty("valueId") private String valueId; @JsonProperty("type") private String type; @JsonIgnore private Map<String, Object> additionalProperties = new LinkedHashMap<String, Object>(); private final static long serialVersionUID = 7326381459761013337L; // getters and setters } package pckg.test; //import @JsonInclude(JsonInclude.Include.NON_NULL) @JsonPropertyOrder({ "id", "occuredOn", "value", "type" }) @Generated("jsonschema2pojo") public class ChangedEvent extends DomainEvent implements Serializable { @JsonProperty("id") private String id; @JsonProperty("occuredOn") private LocalDateTime occuredOn; @JsonProperty("value") private String value; @JsonProperty("type") private String type; @JsonIgnore private Map<String, Object> additionalProperties = new LinkedHashMap<String, Object>(); private final static long serialVersionUID = 5446866391322866265L; //getters and setters }

Configuração do plug-in

Para conectar o plug-in, você precisa adicioná-lo ao arquivo gradle.build e especificar os parâmetros:

• pasta era para gerar DTO

• pacote de novas aulas

• URL da documentação do springwolf

• o nome raiz na documentação, geralmente o nome do serviço

  
  

 plugins { id 'io.github.stepanovd.springwolf2dto' version '1.0.1-alpha' } springWolfDoc2DTO{ url = 'http://localhost:8080/springwolf/docs' targetPackage = 'example.package' documentationTitle = 'my-service' targetDirectory = project.layout.getBuildDirectory().dir("generated-sources") }

Execute a tarefa usando o comando bash:

 ./gradle -q generateDTO

Conclusão

Neste artigo, descrevi como você pode usar o plug-in springwolfdocs2dto para gerar novas classes DTO com base na documentação AsyncApi. Ao mesmo tempo, novas classes estarão de acordo com a herança original e conterão anotações de Jackson para desserialização correta. Espero que você ache este plugin útil para você.