Actualització Canigó 3.8 a Canigó 3.10

A qui va dirigit

Aquesta guia va dirigida a tots aquells usuaris que vulguin actualitzar a Canigó 3.10 la seva aplicació Canigó 3.8.

Versió de Canigó

Els passos descrits en aquest document apliquen a la versió 3.10 del Framework Canigó.

Introducció

Aquesta versió és una versió LTS i es recomana actualitzar les aplicacions Canigó a aquesta versió per tal de tenir un suport continuat, així com la màxima estabilitat que proporciona una versió LTS.

L’objectiu d’aquesta guia és mostrar els procediments necessaris per a actualitzar una aplicació realitzada amb Canigó 3.8 a Canigó 3.10. El punt de partida d’aquesta guia és una aplicació creada amb l’arquetipus maven de Canigó 3.8.

Principals canvis entre Canigó 3.8 i Canigó 3.10

Les principals actualitzacions realitzades en la versió 3.10 respecte la versió 3.8 són les següents:

Configuració prèvia

A la Matriu de Compatibilitats podeu consultar les versions dels mòduls i components de Canigó de les versions 3.8.x i 3.10.x.

Passes a realitzar

Un cop actualitzades les versions dels mòduls, segons s’indica a la secció anterior, serà necessari realitzar els següents passos:

1. Actualitzar la versió de Java de 17 a 21.

Assegureu-vos que el vostre entorn de desenvolupament i els servidors d’execució utilitzen OpenJDK 21. Actualitzeu el pom.xml:

<maven.compiler.source>21</maven.compiler.source>
<maven.compiler.target>21</maven.compiler.target>

2. Actualitzar Hibernate de 5.x a 6.x.

Canigó 3.10 utilitza Hibernate 6.6.39.Final. Això implica diversos canvis importants:

• Les classes de org.hibernate han canviat de paquet en alguns casos.
• El dialecte de la base de dades s’ha d’actualitzar. Per exemple:
  • org.hibernate.dialect.MySQL8Dialect passa a org.hibernate.dialect.MySQLDialect
  • org.hibernate.dialect.PostgreSQLDialect es manté.
  • org.hibernate.dialect.Oracle12cDialect passa a org.hibernate.dialect.OracleDialect

Exemple de configuració actualitzada al fitxer application.yml:

spring:
  jpa:
    properties:
      hibernate:
        dialect: org.hibernate.dialect.MySQLDialect

• Si s’utilitzen @Type de Hibernate, cal migrar a la nova API de org.hibernate.type.

3. Actualitzar QueryDSL de 5.x a 6.x.

Si el projecte utilitza QueryDSL, cal actualitzar les dependències a la versió 6.11 i verificar que la generació de codi Q-classes segueix funcionant correctament. Reviseu el plugin de maven apt-maven-plugin o querydsl-apt per assegurar la compatibilitat amb la nova versió.

   <dependency>
      <groupId>io.github.openfeign.queryds</groupId>
      <artifactId>querydsl-jpa</artifactId>
      <version>6.11</version>
   </dependency>

4. Actualitzar la configuració de Swagger/OpenAPI: migració de Springfox a SpringDoc.

Canigó 3.8 utilitzava springfox-swagger2 3.0.0, mentre que Canigó 3.10 utilitza springdoc-openapi-starter-webmvc-ui 2.8.4. Això requereix diversos canvis importants:

4.1 Reemplaçar la dependència al pom.xml:

Eliminar:

   <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-boot-starter</artifactId>
      <version>3.0.0</version>
   </dependency>

Afegir:

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
      <version>2.8.4</version>
   </dependency>

4.2 Eliminar la classe de configuració de Springfox (SwaggerConfig o similar) i reemplaçar-la amb la configuració de SpringDoc.

Eliminar la configuració basada en Docket:

import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
            .select()
            .apis(RequestHandlerSelectors.basePackage("cat.gencat.ctti"))
            .paths(PathSelectors.any())
            .build();
    }
}

Reemplaçar per la configuració de SpringDoc amb OpenAPI i GroupedOpenApi:

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
            .info(new Info()
                .title("API de l'aplicació")
                .version("1.0")
                .description("Documentació de l'API"));
    }

    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
            .group("public")
            .pathsToMatch("/api/**")
            .build();
    }
}

4.3 Reemplaçar les anotacions de Swagger 2 (io.swagger.annotations) per les anotacions d’OpenAPI 3 (io.swagger.v3.oas.annotations) en tots els controladors i models.

Exemple de migració d’un controlador:

Abans (Springfox / Swagger 2):

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;

@RestController
@RequestMapping("/api/equipaments")
@Api(value = "Equipaments", tags = {"Equipaments"})
public class EquipamentController {

    @GetMapping("/{id}")
    @ApiOperation(value = "Obté un equipament per ID")
    @ApiResponses(value = {
        @ApiResponse(code = 200, message = "Equipament trobat"),
        @ApiResponse(code = 404, message = "Equipament no trobat")
    })
    public ResponseEntity<Equipament> getById(
            @ApiParam(value = "ID de l'equipament", required = true)
            @PathVariable Long id) {
        // ...
    }
}

Després (SpringDoc / OpenAPI 3):

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.tags.Tag;

@RestController
@RequestMapping("/api/equipaments")
@Tag(name = "Equipaments", description = "Operacions sobre equipaments")
public class EquipamentController {

    @GetMapping("/{id}")
    @Operation(summary = "Obté un equipament per ID")
    @ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "Equipament trobat"),
        @ApiResponse(responseCode = "404", description = "Equipament no trobat")
    })
    public ResponseEntity<Equipament> getById(
            @Parameter(description = "ID de l'equipament", required = true)
            @PathVariable Long id) {
        // ...
    }
}

Exemple de migració d’un model:

Abans (Springfox / Swagger 2):

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(description = "Entitat Equipament")
public class Equipament {

    @ApiModelProperty(value = "Identificador", example = "1")
    private Long id;

    @ApiModelProperty(value = "Nom de l'equipament", example = "Equipament 1")
    private String nom;
}

Després (SpringDoc / OpenAPI 3):

import io.swagger.v3.oas.annotations.media.Schema;

@Schema(description = "Entitat Equipament")
public class Equipament {

    @Schema(description = "Identificador", example = "1")
    private Long id;

    @Schema(description = "Nom de l'equipament", example = "Equipament 1")
    private String nom;
}

4.4 Configuració al fitxer application.yml (opcional):

springdoc:
  api-docs:
    path: /api/v3/api-docs
  swagger-ui:
    path: /api/swagger-ui.html
    operationsSorter: method
    tagsSorter: alpha

4.5 Eliminar l’anotació @EnableSwagger2 o @EnableOpenApi si s’utilitza. SpringDoc no requereix cap anotació d’habilitació, ja que es configura automàticament mitjançant Spring Boot autoconfiguration.

La URL d’accés a Swagger segueix sent: http://localhost:8080/api/swagger-ui/index.html

5. Revisar canvis en Spring Boot 3.5.x respecte 3.1.x.

Algunes de les diferències a tenir en compte:

• Autoconfiguration: Spring Boot 3.5 pot introduir noves autoconfigurations. Reviseu que les propietats de application.yml siguin compatibles.
• Spring Security 6.5: Es recomana revisar la configuració de seguretat, ja que hi pot haver canvis en el SecurityFilterChain i la gestió de CSRF.
• Deprecations: Reviseu les classes i mètodes obsolets que puguin haver estat eliminats.

6. Revisar dependències de MongoDB.

Si la vostra aplicació utilitza MongoDB, actualitzeu les dependències del driver:

   <dependency>
      <groupId>org.mongodb</groupId>
      <artifactId>mongodb-driver-sync</artifactId>
      <version>5.5.2</version>
   </dependency>

Per a reactiu:

   <dependency>
      <groupId>org.mongodb</groupId>
      <artifactId>mongodb-driver-reactivestreams</artifactId>
      <version>5.5.2</version>
   </dependency>

Informació sobre mòduls migrats

S’indica el llistat de mòduls que han estat migrats de la versió 3.8 a la 3.10. Per cada mòdul cal modificar els intervals de les versions.

• canigo.root
• canigo.core
• canigo.persistence.core
• canigo.persistence.jpa
• canigo.persistence.mongodb
• canigo.security
• canigo.web.core
• canigo.web.rs
• canigo.support.mailing
• canigo.operation.logging
• canigo.test
• canigo.support.sftp
• canigo.integration.antivirus
• canigo.integration.notificacions.electroniques
• canigo.integration.pica
• canigo.integration.psgd
• canigo.integration.sarcat.pica
• canigo.integration.psis

canigo.root

No aplica realitzar accions addicionals relacionades amb la migració de 3.8 a 3.10.

canigo.core

• Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:

Hi ha uns certs aspectes a tenir en compte també per al connector core:

• La configuració del inicializador de propietats Yaml i propietats del mòdul configurador.
• Configuració del mòdul de logging.
• Configuració del mòdul de internacionalització.

canigo.persistence.core

• Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:

canigo.persistence.jpa

• Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:

• S’ha actualitzat Hibernate de la versió 5.6.7.Final a la 6.6.39.Final. Això pot implicar canvis en els dialectes i en algunes APIs de mapping.

• S’ha actualitzat jackson-databind de la 2.13.2 a la versió 2.21.0.

• S’ha actualitzat mockito-core de la 5.7.0 a la versió 5.21.0.

• Es pot consultar la documentació detallada d’aquest connector en el següent enllaç.

canigo.persistence.mongodb

• Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:

• S’ha actualitzat mongo-java-driver de la 5.0.0 a la versió 5.5.2.
• S’ha actualitzat mongodb-driver-sync de la 4.6.0 a la versió 5.5.2.
• S’ha actualitzat mongodb-driver-reactivestreams de la 4.6.0 a la versió 5.5.2.

Per a més informació d’aquest connector i com configurar-lo, consultar la seva secció corresponent.

canigo.security

• Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:

• S’ha actualitzat Spring Security de la versió 6.1.3 a la 6.5.7. Reviseu la configuració de seguretat per possibles canvis en la API.

Per a més informació d’aquest connector i com configurar-lo, consultar la seva secció corresponent.

canigo.web.core

• Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:

canigo.web.rs

• Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:

canigo.support.mailing

• Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:

Per a més informació d’aquest connector i com configurar-lo, consultar la seva secció corresponent.

canigo.operation.logging

• Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:

• S’ha actualitzat Log4j de la versió 2.22.2 a la 2.25.3.

Per a més informació d’aquest connector i com configurar-lo, consultar la seva secció corresponent.

canigo.test

• Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:

• S’ha actualitzat JUnit Jupiter de la versió 5.10.1 a la 5.14.2.
• S’ha actualitzat mockito-core de la versió 5.7.0 a la 5.21.0.
• S’ha actualitzat Hamcrest de la versió 2.2 a la 3.0.

canigo.support.sftp

• Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:

Per a més informació d’aquest connector i com configurar-lo, consultar la seva secció corresponent.

canigo.integration.antivirus

• Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:

Per a més informació d’aquest connector i com configurar-lo, consultar la seva secció corresponent.

canigo.integration.notificacions.electroniques

• Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:

Per a més informació d’aquest connector i com configurar-lo, consultar la seva secció corresponent.

canigo.integration.pica

• Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:

Per a més informació d’aquest connector i com configurar-lo, consultar la seva secció corresponent.

canigo.integration.psgd

• Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:

Per a més informació d’aquest connector i com configurar-lo, consultar la seva secció corresponent.

canigo.integration.sarcat.pica

• Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:

Per a més informació d’aquest connector i com configurar-lo, consultar la seva secció corresponent.

canigo.integration.psis

• Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:

Per a més informació d’aquest connector i com configurar-lo, consultar la seva secció corresponent.