Diferencias

Muestra las diferencias entre dos versiones de la página.

--- ada:howto:sicoferp:factory:migracionsicoferp:process:backend:guiadocmicroservicios [2020/05/19 18:41]
carlos.torres creado
+++ ada:howto:sicoferp:factory:migracionsicoferp:process:backend:guiadocmicroservicios [2020/05/19 19:02] (actual)
carlos.torres
@@ Línea 10: / Línea 10: @@
 ===== Documentación de Soporte =====
-En la siguiente web se relacionan la forma de implementación de la especificación OAS con la tecnología Sprintboot
+En la siguiente web se relacionan la forma de implementación de la especificación OAS((https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md)) con la tecnología Sprintboot
 [[https://springdoc.org/|Documentación springdoc]]
 ===== Configuraciones del Microservicio =====
-Todo microservicio que realice persistencia de datos o que consuma servicios que devuelvan entidades debe incluir en su archivo de configuración Maven **POM**((https://www.tutorialspoint.com/maven/maven_pom.htm)) la dependencia del proyecto del Dominio de clases y entidades Comunes el cual se describe a continuación:
+Todo microservicio que implemente documentación OAS((https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md)) debe incluir en su archivo de configuración Maven **POM**((https://www.tutorialspoint.com/maven/maven_pom.htm)) la dependencia del proyecto del Dominio de clases y entidades Comunes el cual se describe a continuación:
 <code xml>
@@ Línea 26: / Línea 26: @@
 El desarrollador debe utilizar la versión más reciente del proyecto la cual puede ser consultada en la sección [[ada:howto:sicoferp:factory:migracionsicoferp:process:backend:apiversion | Versionamiento de APIs]]
-==== Como usar el Dominio de Clases de Entidades Comunes  ====
+===== Como implementar documentación OAS con el Dominio de Clases de Entidades Comunes  =====
-Para usar el Dominio de Clases de Entidades Comunes siga los siguientes pasos:
+Para usar el Dominio de Clases de Entidades Comunes en el proceso de documentación siga los siguientes pasos:
-  * Registre la dependencia actualizada del Dominio de Clases de Entidades Comunes.
-  * Registre en la clase principal del Microservicio la anotación <code java>@EntityScan({"array de clases o paquetes"}) </code>con las clases o paquetes que desea utilizar.
-  * Importe las clases que desea utilizar en las clases del microservicio.
-==== Implementar soporte de bases de datos ====
-Para implementar el soporte de bases de datos realice lso siguientes pasos:
 === Paso 1 ===
@@ Línea 40: / Línea 33: @@
 === Paso 2 ===
-cree un paquete llamado dbconnect
+Cree un paquete llamado config
 === Paso 3 ===
-Cree el datasource interceptor como se muestra continuación.
+Cree la clase de configuración como se muestra continuación.
 <code java>
-package co.ada.test.microservice.prueba.dbconnect;
+package co.ada.test.microservicio.pruebamodel.config;
-import org.springframework.stereotype.Component;
+import org.springframework.context.annotation.Configuration;
-import co.ada.db.config.DataSourceInterceptor;
+import co.ada.doc.config.SpringOpenApiConfigBase;
-@Component
+@Configuration
-public class MyDataSourceInterceptor extends DataSourceInterceptor {}
+public class MySpringOpenApiConfig extends SpringOpenApiConfigBase {}
 </code>
 === Paso 4 ===
-Cree la clase de configuración como se muestra continuación.
+Configure en el bootstrap.yml del proyecto los parametros de documentación del microservicio. Apoyese del siguiente modelo de referencia extraido del proyecto modelo.
-<code java>package co.ada.test.microservice.prueba.dbconnect;
+<code yaml>
+openapi-document:
-import org.springframework.context.annotation.Configuration;
+   info:
+      title: "Prueba Model ADA API"
-import co.ada.db.config.WebConfig;
+      description: "Ejemplo de Microservicio utilizando el Dominio de clases y entidades comunes"
+      termsOfService: ""
-@Configuration
+      contact:
-public class MyWebConfig extends WebConfig {}
+         name: "Carlos Torres"
-</code>
+         url: "http://ada.co"
+         email: "carlos.torres@ada.co"
+      license:
+         name: "ADA 1.0"
+         url: ""
+      version: "0.0.1"
+   servers:
+      public:
+         url: "http://zuul-mig.adacsc.co/api/prueba"
+         description: "Development integration public server"
+   externalDocs:
+      description: ""
+      url: ""</code>
 === Paso 5 ===
-Cree la clase de configuración de repositorio teniendo presente el siguiente ejemplo:
+Documente las clases del microservicio con la especificación OAS((https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md)). Apoyese del proyecto modelo el cual tiene un ejemplo de configuración.
 <code java>
-package co.ada.test.microservice.prueba.dbconnect;
+//EJEMPLO CONTROLADOR
+package co.ada.test.microservicio.pruebamodel.controller;
+import java.util.List;
 import org.springframework.beans.factory.annotation.Autowired;
-import org.springframework.beans.factory.annotation.Qualifier;
+import org.springframework.http.HttpStatus;
-import org.springframework.boot.orm.jpa.EntityManagerFactoryBuilder;
+import org.springframework.http.ResponseEntity;
-import org.springframework.context.annotation.Bean;
+import org.springframework.web.bind.annotation.GetMapping;
-import org.springframework.context.annotation.Configuration;
+import org.springframework.web.bind.annotation.RestController;
-import org.springframework.data.jpa.repository.config.EnableJpaRepositories;
-import org.springframework.orm.jpa.JpaTransactionManager;
-import org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean;
-import org.springframework.transaction.annotation.EnableTransactionManagement;
-import co.ada.db.config.DataSourceConfigBase;
+import co.ada.core.controller.AdaController;
-import co.ada.db.config.IDataSourceConfig;
+import co.ada.models.microservicio.usuario.Employee;
+import co.ada.models.microservicio.usuario.Usuario;
+import co.ada.test.microservicio.pruebamodel.service.EmployeeService;
+import co.ada.test.microservicio.pruebamodel.service.UserService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
-@Configuration
+@Tag(name = "Controlador Servicios", description = "Controlador de prueba de Servicios de ejemplo")
-@EnableJpaRepositories(
+@RestController
-		basePackages = "co.ada.test.microservice.prueba.repo",//Ver Nota 1
+public class ServiciosController extends AdaController{
-		transactionManagerRef = "transcationManager",
-		entityManagerFactoryRef = "entityManager")
-@EnableTransactionManagement
-public class MyDataSourceConfig extends DataSourceConfigBase {
-	@Bean(name = "entityManager")
+	@Autowired
-	public LocalContainerEntityManagerFactoryBean entityManagerFactoryBean(EntityManagerFactoryBuilder builder) {
+	private EmployeeService employeeService;
-		return builder.dataSource(dataSource()).packages("co.ada.models.microservicio.usuario").build();//Ver Nota 2
-	}
+	@Autowired
+	private UserService usuarioServicie;
-	@Bean(name = "transcationManager")
+	@Operation(summary = "Consultar Empleados", description = "Ejemplo de documentación de servicio de lista de empleados")
-	public JpaTransactionManager transactionManager(@Autowired @Qualifier("entityManager") LocalContainerEntityManagerFactoryBean entityManagerFactoryBean) {
+	@GetMapping(value = "employee")
-		return new JpaTransactionManager(entityManagerFactoryBean.getObject());
+	public ResponseEntity<List<Employee>> getEmployees() {
+		return ResponseEntity.status(HttpStatus.ACCEPTED).body(employeeService.getEmployees());
 	}
+	@Operation(summary = "Consultar Usuarios", description = "Ejemplo de documentación de servicio de lista de usuarios")
+	@GetMapping(value = "usuarios")
+	public ResponseEntity<List<Usuario>> getUsuarios() {
+		return ResponseEntity.status(HttpStatus.ACCEPTED).body(usuarioServicie.getUsuarios());
+	}
 }
 </code>
-== Nota 1 ==
+<code java>
-Registre el paquete local donde tiene los repositorios / dao de acceso a datos.
+//EJEMPLO ENTIDAD
+package co.ada.models.microservicio.usuario;
-== Nota 2 ==
+import java.io.Serializable;
-Registre el paquete de entidades del Dominio de Clases de Entidades Comunes que utilizará con los repositorio.
-==== Repositorios ====
+import javax.persistence.Column;
-Se define en el Dominio de Clases de Entidades Comunes el repositorio estandar para acceso a datos el cual debe ser utilizado en todos los microservicios que requieran esa funcionalidad. El repositorio esta ubica en el paquete co.ada.db.config.repository y contiene la clase que a continuación se describe:
+import javax.persistence.Entity;
+import javax.persistence.GeneratedValue;
+import javax.persistence.GenerationType;
+import javax.persistence.Id;
+import javax.persistence.Table;
+import javax.validation.constraints.NotNull;
-<code java>
+import io.swagger.v3.oas.annotations.media.Schema;
-package co.ada.db.config.repository;
-import org.springframework.data.jpa.repository.JpaRepository;
+@Schema(
-import org.springframework.stereotype.Repository;
+	     name = "Rol",
+	     description = "Clase entidad que contiene la definición de la tabla Rol"
+	)
+@Entity
+@Table(name="roles")
+public class Role implements Serializable {
-@Repository
+	/**
-public interface JpaAdaRepository<T, ID> extends JpaRepository<T, ID> {}
+	 *
+	 */
+	private static final long serialVersionUID = 6595145379859167872L;
+	@NotNull
+	@Id
+	@GeneratedValue(strategy = GenerationType.IDENTITY)
+	private Long id;
+	@NotNull
+	@Column(unique = true, length = 128)
+	private String nombre;
+	public Role() {}
+	public Long getId() {
+		return id;
+	}
+	public void setId(Long id) {
+		this.id = id;
+	}
+	public String getNombre() {
+		return nombre;
+	}
+	public void setNombre(String nombre) {
+		this.nombre = nombre;
+	}
+}
 </code>
+==== Recomendaciones ====
+  * Toda documentación debe ser clara y precisa.
+  * Toda entidad debe estar documentada en la especificación OAS para ser incluida en el Dominio de clases y Entidades Comunes.
+  * Todo Controller debe ser documentado mínimo en todas las operaciones expuestas.
+  * Cada operación expuesta debe documentar los códigos de retorno generados en el consumo.
 [[ada:howto:sicoferp:factory:migracionsicoferp:process:backend|←Volver atrás]]

Wiki

Herramientas de usuario

Herramientas del sitio

Diferencias

Herramientas de la página