ClinicaVoll_Alura

ONE | Fase 3 - Especialización Back-End G6 Alura - Oracle Next Education

Este curso va a desarrollar una API REST para un consultorio médico ficticio llamado Voll.med. Como el curso está enfocado únicamente en la construcción de una API REST utilizando Java y Spring, no habrá ningún tipo de interfaz por parte del usuario, pero sí un desafío para mí hacer una aplicación del lado del cliente que se integre con esta API.

1er. Curso de Spring Boot 3: desarrollar una API Rest en Java

• Cree una API Rest de Java desde cero con Spring Boot
• Desarrolle CRUD usando la base de datos MySQL
• Use Flyway como una herramienta de migración de API
• Realizar validaciones usando Bean Validation
• Realizar paginación de datos API

2do. Curso Spring Boot 3: aplique las mejores prácticas y proteja una API Rest

• Aprenda buenas practicas en diseño de API
• Aprenda fundamentos basicos de autenticación y autorización
• Aprenda a retornar codigos de error HTTP
• Aprenda fundamentos de Spring Security

3er. Curso Spring Boot 3: documentar, probar y preparar una API para su implementación

• Aprenda a aislar código de reglas de negocio en una aplicación
• Implementar principios SOLID
• Documentar una API siguiendo el estándar OpenAPI
• Aprenda a escribir pruebas automatizadas en una aplicación con Spring Boot
• Cree una aplicación con Spring Boot
• Use variables de entorno y prepare una aplicación para su implementación

Configurando el entorno Java

]

Asegúrese de tener instalado o contar con herramientas como:

• Git y GitHub
• IntelliJ IDEA Community Edition
• Java JDK: versión: 17 en adelante
• Spring Initializr - https://start.spring.io/
• MySQL relational database management system (RDBMS)
• MySQL Workbench: SQL Development
• Insomnia o Postman

Dependencias para agregar al crear el proyecto en Spring Initializr:

• Spring Data JPA
• Lombok
• Spring Web
• Spring Boot DevTools
• Flyway Migration
• MySQL Driver
• Validation
• Spring Security
• Springdoc

 

Construcción de la base de datos

Para integrar una base de datos a nuestro proyecto Spring, nos solicitaron agregar algunas dependencias en nuestro pom.xml :

• Validation
• MySQL Driver
• Spring Data JPA
• Flyway Migration

 

Base de datos MySQL (Nombre de esquema utilizado en este Challenge: vollmed_api)

Diagrama implementado para crear base de datos:

Note

Antes de pasar a la etapa de migraciones del proyecto, te sugerimos crear la base de datos y configurarla según se mencionó anteriormente.

Migración en el proyecto

Las migraciones son comandos en lenguaje SQL para la configuración de la base de datos creada.

[!IMPORTANTE] Recuerda siempre pausar/detener la ejecución del proyecto Spring para crear/cambiar las migraciones.

Formato para crear archivo sql para Flyway Migration:

V1__create-table-medicos.sql
V2__alter-table-medicos-add-telefono.sql
V3__alter-table-medicos-add-activo.sql
V4__create-table-usuarios.sql
V5__create-table-pacientes.sql
V6__create-table-consultas.sql
V7__alter-table-consultas-add-motivo.sql
.

Tabla creadas en la base de datos, con registro de versiones Flyway Migration

forohub_alura.flyway_schema_history

y observamos el contenido de la tabla:

 

Pruebas de la API

Las pruebas de las funcionalidades de la API pueden realizarse utilizando alguna herramienta de pruebas de API, como Postman o Insomnia.

En este caso utilizamos: Insomnia: https://insomnia.rest para probar la API, como por ejemplo:

Obtener Usuarios registrados en la base de datos:

 

Autenticación con Spring Security

Implementa un mecanismo de autenticación en la API para que los usuarios puedan autenticarse y enviar solicitudes a ella. A partir de ahora, solo los usuarios autenticados pueden interactuar con la API.

Note

Recuerda agregar la dependencia Spring Security en tu archivo pom.xml (si aún no lo has hecho en la etapa de configuración del entorno Java y Spring).

Configuración de seguridad

Para configurar la autenticación en tu proyecto, es necesario definir tu clase SecurityConfigurations con información para el acceso a través de solicitudes http, utilizando anotaciones como @Configuration y @EnableWebSecurity, así como la clase spring HttpSecurity.

Fragmento de Codigo de la clase SecurityConfigurations:

 // Resto del código omitido...
 /**
 * Configuración de seguridad para la aplicación.
 */
@Configuration
@EnableWebSecurity
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class SecurityConfigurations {

    // Lista de rutas que se permiten sin autenticación
    private static final String[] AUTH_WHITELIST = {
            "/usuarios/**",
            "/v3/api-docs/**",
            "/swagger-ui/**",
            "/swagger-ui.html"
    };

    // Inyección del filtro de seguridad personalizado
    @Autowired
    private SecurityFilter securityFilter;

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity httpSecurity) throws Exception {
        return httpSecurity
                .csrf(csrf -> csrf.disable()) // Desactiva la protección CSRF para APIs RESTful
                 // Configura la política de sesión como stateless
                .sessionManagement(sess -> sess.sessionCreationPolicy(SessionCreationPolicy.STATELESS)) 
                .authorizeHttpRequests(auth -> auth
                        // Permitir todas las solicitudes POST al endpoint /login
                        .requestMatchers(HttpMethod.POST, "/login").permitAll()
                        // Permitir las rutas en AUTH_WHITELIST sin autenticación
                        .requestMatchers(AUTH_WHITELIST).permitAll()
                        // Permitir el registro de usuarios
                        .requestMatchers(HttpMethod.POST, "/usuario/register").permitAll()
                        // Proteger las rutas /admin/** solo para usuarios con el rol ADMIN
                        .requestMatchers("/admin/**").hasAuthority(ADMIN.name())
                        .requestMatchers(HttpMethod.POST, "/cursos/**").hasAuthority(ADMIN.name())
 // Resto del código omitido...

 

Documentación con Swagger - (Opcional)

Se nos solicito documentar nuestra API con Spring Swagger. Swagger es una herramienta extremadamente ventajosa para tu API, ya que ofrece una interfaz amigable y accesible, así como una forma de documentación automática generada simultáneamente con el desarrollo de la API. Es una herramienta basada en el estándar OpenAPI que nos permite documentar y probar nuestros Web APIs,

Accediendo a la interfaz gráfica - Swagger UI

Una vez realizada la configuración, ya podremos acceder a la interfaz gráfica de Swagger desde la dirección http://localhost:8080/swagger-ui/index.html. El resultado sería el siguiente:

Ingresando a Autenticacion- Login de la interface realizamos el login con datos email y contraseña del usuario registrado. Realizamos un clic en Execute:

Como resultado obtenemos un estado Code 200, si el login es valido. En el body se encuentra el token generado:

Se ha incluido un botón [ Authorize ] en la interfaz, que nos permitirá añadir un Token JWT a la cabecera de las peticiones HTTP que realicemos hacia los Controladores de Web API. Copiamos el token generado y lo pegamos dentro de Autorize , en el campo value y clickeamos Authorize:

 

Ejecución del Proyecto

Para ejecutar el proyecto, sigue estos pasos:

• Clona o descarga desde Github el repositorio en tu disco local.
• Importa el proyecto en tu IDE de Java (este proyecto se realizo en IntelliJ IDEA).
• Configura las dependencias y ajusta la configuración según sea necesario.
• Corre la aplicación para interactuar con la base de datos y alguna herramienta de pruebas de API, como Postman o Insomnia.

Glossary

• DTO (Data Transfer Object): Objetos utilizados para transferir datos entre el backend y el frontend.
• JPA (Java Persistence API): API estándar de Java para mapear objetos a una base de datos relacional.
• Hibernate: Framework de mapeo objeto-relacional para Java.
• API (Application Programming Interface): Conjunto de reglas y definiciones que permite a las aplicaciones interactuar entre sí.
• DTO (Data Transfer Object): Patrón de diseño que se utiliza para transferir datos entre subsistemas de un software. En este contexto, se utilizan para transferir datos entre el backend y el frontend de la aplicación.
• JPA (Java Persistence API): API estándar de Java para el mapeo objeto-relacional. Permite mapear objetos de dominio a tablas de base de datos y viceversa.
• Hibernate: Framework de mapeo objeto-relacional para Java. Facilita el trabajo con JPA y proporciona funcionalidades adicionales para interactuar con la base de datos.
• Spring Boot: Framework de desarrollo de aplicaciones Java que facilita la creación de aplicaciones basadas en Spring con una configuración mínima. Proporciona un conjunto de bibliotecas y herramientas que simplifican el desarrollo de aplicaciones empresariales.
• PostgreSQL: Sistema de gestión de bases de datos relacional de código abierto y potente. Se utiliza en este proyecto como el motor de base de datos para almacenar los libros y autores.
• Maven: Herramienta de gestión de proyectos de software que se utiliza para construir y gestionar proyectos Java. Facilita la gestión de dependencias, la compilación y la ejecución de pruebas, entre otras tareas.
• DataSource: Configuración que define la conexión a la base de datos, incluyendo la URL, el nombre de usuario y la contraseña.
• Hibernate Dialect: Configuración que especifica el dialecto SQL que Hibernate debe utilizar para interactuar con la base de datos. En este caso, se utiliza el dialecto de HSQL.
• Spring Data JPA: Parte del ecosistema de Spring que simplifica el acceso a datos en aplicaciones basadas en Spring. Proporciona una abstracción sobre JPA y facilita la implementación de repositorios de datos.
• CascadeType: Enumeración que define las operaciones de cascada que deben aplicarse a las relaciones entre entidades. Por ejemplo, si se elimina un autor, las operaciones en cascada pueden eliminar automáticamente los libros asociados a ese autor.
• FetchType: Enumeración que define cómo se cargan los datos asociados a una relación entre entidades. FetchType.EAGER indica que los datos deben cargarse de forma inmediata, mientras que FetchType.LAZY indica que los datos deben cargarse solo cuando sean necesarios.
• Principal: En el contexto de este proyecto, se refiere a la clase principal que coordina las operaciones principales de la aplicación, como la consulta y el almacenamiento de datos.
• Estructura del Proyecto: Organización y disposición de los archivos y paquetes que componen el proyecto. Una estructura de proyecto bien definida facilita la comprensión y el mantenimiento del código.
• Diagrama de Estructura del Proyecto: Representación visual de la estructura del proyecto, que muestra cómo se relacionan los diferentes componentes y cómo fluye la información a través de ellos. Ayuda a comprender la arquitectura y el diseño del proyecto.

MIT License

Copyright (c) [2024] [Hernando Muñoz J]

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Copyright (c) [2024] [Hernando Muñoz J]

Se concede permiso, de forma gratuita, a cualquier persona que obtenga una copia
de este software y de los archivos de documentación asociados (el "Software"), para tratar
con el Software sin restricciones, incluyendo sin limitación los derechos
para usar, copiar, modificar, fusionar, publicar, distribuir, sublicenciar y/o vender
copias del Software, y para permitir a las personas a las que se les proporcione el Software
para hacerlo, sujeto a las siguientes condiciones:

El aviso de copyright anterior y este aviso de permiso se incluirán en todas las
copias o porciones sustanciales del Software.

EL SOFTWARE SE PROPORCIONA "TAL CUAL", SIN GARANTÍA DE NINGÚN TIPO, EXPRESA O
IMPLÍCITA, INCLUYENDO PERO NO LIMITADO A LAS GARANTÍAS DE COMERCIABILIDAD,
IDONEIDAD PARA UN PROPÓSITO PARTICULAR Y NO INFRACCIÓN. EN NINGÚN CASO LOS
AUTORES O TITULARES DE DERECHOS DE AUTOR SERÁN RESPONSABLES DE CUALQUIER RECLAMO, DAÑOS U OTROS
RESPONSABILIDAD, YA SEA EN UNA ACCIÓN DE CONTRATO, AGRAVIO O DE OTRO MODO, QUE SURJA DE,
FUERA O EN RELACIÓN CON EL SOFTWARE O EL USO U OTROS TRATOS EN EL
SOFTWARE.