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 é 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.   , descrevi como configurar uma dessas ferramentas   . AsyncApi Neste artigo 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   para resolver esse problema. No entanto, no processo de tentar implementar meu plano, encontrei vários problemas: jsonschema2pojo  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   se transformou em uma classe separada Flags e todo o valor da coleção em si cairá no campo   . Map<String, Boolean> 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   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ê. springwolfdocs2dto

Read My Stories

Este áudio é produzido no idioma original da história!

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

About Author

COMENTARIOS

Rótulos

ESTE ARTIGO FOI APRESENTADO EM

Related Stories

Guia do arquiteto para construir arquitetura de referência para um Datalake de IA/ML

Criando produtos criptográficos centrados no usuário: a importância do feedback do cliente

As camadas invisíveis: por que as entrevistas com usuários são um ativo insubstituível

Navegando pelas águas: desenvolvendo aplicações RAG de nível de produção com data lakes

Guia do arquiteto para construir arquitetura de referência para um Datalake de IA/ML

Criando produtos criptográficos centrados no usuário: a importância do feedback do cliente

As camadas invisíveis: por que as entrevistas com usuários são um ativo insubstituível

Navegando pelas águas: desenvolvendo aplicações RAG de nível de produção com data lakes

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps