S02L01 - RestApi de Spring Boot, demostración de JWT

html

Integrando Swagger y JWT en Spring Boot RESTful APIs: Una Guía Completa

Tabla de Contenidos

Introducción
Entendiendo Swagger
Introducción a JWT (JSON Web Tokens)
Configurando Swagger en Spring Boot
Implementando Autenticación JWT
Personalizando Swagger UI
Probando APIs con Swagger
Mejores Prácticas y Consideraciones de Seguridad
Conclusión


Introducción
En el ámbito del desarrollo web moderno, crear APIs seguras y bien documentadas es fundamental. Este eBook profundiza en la integración de Swagger y JWT (JSON Web Tokens) dentro de Spring Boot RESTful APIs. Al aprovechar Swagger para la documentación de APIs y JWT para la autenticación, los desarrolladores pueden construir aplicaciones robustas, seguras y fácilmente mantenibles. Esta guía está diseñada para principiantes y desarrolladores con conocimientos básicos, proporcionando instrucciones claras, concisas y ejemplos prácticos.

Entendiendo Swagger
¿Qué es Swagger?
Swagger es un framework de código abierto que ayuda en el diseño, construcción, documentación y consumo de servicios web RESTful. Proporciona una interfaz amigable para visualizar e interactuar con los recursos de la API sin ninguna lógica de implementación.
Características Clave de Swagger

Documentación de API: Genera automáticamente documentación interactiva.
Pruebas de API: Facilita la prueba de endpoints directamente desde la UI.
Definiciones de Esquema: Define modelos de datos y estructuras para solicitudes y respuestas.

Importancia de Swagger en el Desarrollo de APIs
Swagger mejora el flujo de trabajo de desarrollo al proporcionar una documentación clara, lo cual es crucial para la colaboración y el mantenimiento. Simplifica el proceso de comprensión de los endpoints de la API y sus funcionalidades.

Introducción a JWT (JSON Web Tokens)
¿Qué es JWT?
JWT (JSON Web Token) es un medio compacto y seguro para representar afirmaciones que se transfieren entre dos partes. Se utiliza ampliamente para la autenticación y autorización en aplicaciones web.
Componentes Clave de JWT

Header: Contiene metadatos sobre el token, incluyendo el tipo y el algoritmo de firma.
Payload: Contiene las afirmaciones o declaraciones sobre el usuario o entidad.
Signature: Asegura la integridad del token verificando que no ha sido alterado.

Ventajas de Usar JWT

Autenticación sin Estado: Elimina la necesidad de sesiones del lado del servidor.
Escalabilidad: Adecuado para sistemas distribuidos y microservicios.
Seguridad: Codifica la información del usuario de manera segura con un tiempo de expiración.


Configurando Swagger en Spring Boot
Requisitos Previos

Conocimientos básicos de Spring Boot.
Java Development Kit (JDK) instalado.
Herramienta de construcción Maven o Gradle.

Integración Paso a Paso

Agregar Dependencias de Swagger





		
		
			
			
Java
			
			// pom.xml
<dependencies>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-boot-starter</artifactId>
        <version>3.0.0</version>
    </dependency>
</dependencies>
			
				
					
				
					1
2
3
4
5
6
7
8
				
						// pom.xml
<dependencies>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-boot-starter</artifactId>
        <version>3.0.0</version>
    </dependency>
</dependencies>
					
				
			
		


Configurar Swagger




		
		
			
			
Java
			
			// SwaggerConfig.java
package com.example.demo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
                .paths(PathSelectors.any())
                .build();
    }
}
			
				
					
				
					1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
				
						// SwaggerConfig.java
package com.example.demo.config;
 
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
 
@Configuration
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
                .paths(PathSelectors.any())
                .build();
    }
}
					
				
			
		


Acceder a Swagger UI
Inicia la aplicación Spring Boot y navega a http://localhost:8080/swagger-ui/ para ver la documentación interactiva de la API.

Implementando Autenticación JWT
¿Por Qué Usar JWT?
JWT proporciona una manera segura y eficiente de manejar la autenticación y autorización en aplicaciones sin estado. Asegura que cada solicitud esté autenticada sin mantener sesiones del lado del servidor.
Configurar JWT en Spring Boot

Agregar Dependencias de JWT





		
		
			
			
Java
			
			// pom.xml
<dependencies>
    <dependency>
        <groupId>io.jsonwebtoken</groupId>
        <artifactId>jjwt</artifactId>
        <version>0.9.1</version>
    </dependency>
</dependencies>
			
				
					
				
					1
2
3
4
5
6
7
8
				
						// pom.xml
<dependencies>
    <dependency>
        <groupId>io.jsonwebtoken</groupId>
        <artifactId>jjwt</artifactId>
        <version>0.9.1</version>
    </dependency>
</dependencies>
					
				
			
		


Crear Clase Utilitaria de JWT




		
		
			
			
Java
			
			// JwtUtil.java
package com.example.demo.util;

import io.jsonwebtoken.Claims;
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;
import org.springframework.stereotype.Component;

import java.util.Date;
import java.util.HashMap;
import java.util.Map;
import java.util.function.Function;

@Component
public class JwtUtil {
    private String SECRET_KEY = "secret";

    public String extractUsername(String token) {
        return extractClaim(token, Claims::getSubject);
    }

    public Date extractExpiration(String token) {
        return extractClaim(token, Claims::getExpiration);
    }

    public <T> T extractClaim(String token, Function<Claims, T> claimsResolver) {
        final Claims claims = extractAllClaims(token);
        return claimsResolver.apply(claims);
    }

    private Claims extractAllClaims(String token) {
        return Jwts.parser().setSigningKey(SECRET_KEY).parseClaimsJws(token).getBody();
    }

    private Boolean isTokenExpired(String token) {
        return extractExpiration(token).before(new Date());
    }

    public String generateToken(String username) {
        Map<String, Object> claims = new HashMap<>();
        return createToken(claims, username);
    }

    private String createToken(Map<String, Object> claims, String subject) {
        return Jwts.builder().setClaims(claims).setSubject(subject).setIssuedAt(new Date(System.currentTimeMillis()))
                .setExpiration(new Date(System.currentTimeMillis() + 1000 * 60 * 60 * 10))
                .signWith(SignatureAlgorithm.HS256, SECRET_KEY).compact();
    }

    public Boolean validateToken(String token, String username) {
        final String extractedUsername = extractUsername(token);
        return (extractedUsername.equals(username) && !isTokenExpired(token));
    }
}
			
				
					
				
					1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
				
						// JwtUtil.java
package com.example.demo.util;
 
import io.jsonwebtoken.Claims;
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;
import org.springframework.stereotype.Component;
 
import java.util.Date;
import java.util.HashMap;
import java.util.Map;
import java.util.function.Function;
 
@Component
public class JwtUtil {
    private String SECRET_KEY = "secret";
 
    public String extractUsername(String token) {
        return extractClaim(token, Claims::getSubject);
    }
 
    public Date extractExpiration(String token) {
        return extractClaim(token, Claims::getExpiration);
    }
 
    public <T> T extractClaim(String token, Function<Claims, T> claimsResolver) {
        final Claims claims = extractAllClaims(token);
        return claimsResolver.apply(claims);
    }
 
    private Claims extractAllClaims(String token) {
        return Jwts.parser().setSigningKey(SECRET_KEY).parseClaimsJws(token).getBody();
    }
 
    private Boolean isTokenExpired(String token) {
        return extractExpiration(token).before(new Date());
    }
 
    public String generateToken(String username) {
        Map<String, Object> claims = new HashMap<>();
        return createToken(claims, username);
    }
 
    private String createToken(Map<String, Object> claims, String subject) {
        return Jwts.builder().setClaims(claims).setSubject(subject).setIssuedAt(new Date(System.currentTimeMillis()))
                .setExpiration(new Date(System.currentTimeMillis() + 1000 * 60 * 60 * 10))
                .signWith(SignatureAlgorithm.HS256, SECRET_KEY).compact();
    }
 
    public Boolean validateToken(String token, String username) {
        final String extractedUsername = extractUsername(token);
        return (extractedUsername.equals(username) && !isTokenExpired(token));
    }
}
					
				
			
		


Crear Controlador de Autenticación




		
		
			
			
Java
			
			// AuthController.java
package com.example.demo.controller;

import com.example.demo.util.JwtUtil;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
public class AuthController {

    @Autowired
    private JwtUtil jwtUtil;

    @PostMapping("/token")
    public ResponseEntity<?> generateToken(@RequestBody AuthRequest authRequest) {
        // Autenticar usuario
        String token = jwtUtil.generateToken(authRequest.getUsername());
        return ResponseEntity.ok(new AuthResponse(token));
    }
}

// AuthRequest.java
package com.example.demo.controller;

public class AuthRequest {
    private String username;
    private String password;

    // Getters y Setters
}

// AuthResponse.java
package com.example.demo.controller;

public class AuthResponse {
    private final String token;

    public AuthResponse(String token) {
        this.token = token;
    }

    public String getToken() {
        return token;
    }
}
			
				
					
				
					1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
				
						// AuthController.java
package com.example.demo.controller;
 
import com.example.demo.util.JwtUtil;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
 
@RestController
public class AuthController {
 
    @Autowired
    private JwtUtil jwtUtil;
 
    @PostMapping("/token")
    public ResponseEntity<?> generateToken(@RequestBody AuthRequest authRequest) {
        // Autenticar usuario
        String token = jwtUtil.generateToken(authRequest.getUsername());
        return ResponseEntity.ok(new AuthResponse(token));
    }
}
 
// AuthRequest.java
package com.example.demo.controller;
 
public class AuthRequest {
    private String username;
    private String password;
 
    // Getters y Setters
}
 
// AuthResponse.java
package com.example.demo.controller;
 
public class AuthResponse {
    private final String token;
 
    public AuthResponse(String token) {
        this.token = token;
    }
 
    public String getToken() {
        return token;
    }
}
					
				
			
		



Personalizando Swagger UI
Actualizando Información de la Aplicación
Puedes personalizar la Swagger UI con detalles específicos de la aplicación como nombre, versión y descripción.




		
		
			
			
Java
			
			// SwaggerConfig.java
@Bean
public Docket api() {
    return new Docket(DocumentationType.OAS_30)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
            .paths(PathSelectors.any())
            .build()
            .apiInfo(apiInfo());
}

private ApiInfo apiInfo() {
    return new ApiInfo(
            "User API",
            "Spring Boot RESTful API Demo",
            "1.0",
            "Términos de servicio",
            new Contact("Tu Nombre", "www.ejemplo.com", "tu@ejemplo.com"),
            "Licencia de la API",
            "URL de la licencia de la API",
            Collections.emptyList());
}
			
				
					
				
					1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
				
						// SwaggerConfig.java
@Bean
public Docket api() {
    return new Docket(DocumentationType.OAS_30)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
            .paths(PathSelectors.any())
            .build()
            .apiInfo(apiInfo());
}
 
private ApiInfo apiInfo() {
    return new ApiInfo(
            "User API",
            "Spring Boot RESTful API Demo",
            "1.0",
            "Términos de servicio",
            new Contact("Tu Nombre", "www.ejemplo.com", "tu@ejemplo.com"),
            "Licencia de la API",
            "URL de la licencia de la API",
            Collections.emptyList());
}
					
				
			
		


Agregando Autorización a Swagger
Swagger UI permite agregar encabezados de autorización a las solicitudes de API, lo que habilita pruebas autenticadas.

Configurar Esquemas de Seguridad





		
		
			
			
Java
			
			// SwaggerConfig.java
@Bean
public Docket api() {
    return new Docket(DocumentationType.OAS_30)
            .securitySchemes(Arrays.asList(apiKey()))
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
            .paths(PathSelectors.any())
            .build();
}

private ApiKey apiKey() {
    return new ApiKey("JWT", "Authorization", "header");
}
			
				
					
				
					1
2
3
4
5
6
7
8
9
10
11
12
13
14
				
						// SwaggerConfig.java
@Bean
public Docket api() {
    return new Docket(DocumentationType.OAS_30)
            .securitySchemes(Arrays.asList(apiKey()))
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
            .paths(PathSelectors.any())
            .build();
}
 
private ApiKey apiKey() {
    return new ApiKey("JWT", "Authorization", "header");
}
					
				
			
		


Autorizar Usando JWT

Haz clic en el botón "Authorize" en Swagger UI.
Introduce el token JWT precedido por Bearer  (por ejemplo, Bearer tu_token_jwt).
Una vez autorizado, Swagger incluirá el token en las solicitudes de API posteriores.


Probando APIs con Swagger
Realizando Solicitudes Autenticadas

Generar Token JWT

Usa el endpoint /token con credenciales válidas para recibir un JWT.

Autorizar Swagger UI

Haz clic en "Authorize" e introduce el token como se describió anteriormente.

Acceder a Endpoints Protegidos

Con la autorización establecida, ahora puedes acceder a APIs protegidas directamente desde Swagger UI.


Código de Programa de Ejemplo




		
		
			
			
Java
			
			// SampleController.java
package com.example.demo.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class SampleController {

    @GetMapping("/homepage")
    public String homepage() {
        return "homepage";
    }
}
			
				
					
				
					1
2
3
4
5
6
7
8
9
10
11
12
13
14
				
						// SampleController.java
package com.example.demo.controller;
 
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
 
@RestController
public class SampleController {
 
    @GetMapping("/homepage")
    public String homepage() {
        return "homepage";
    }
}
					
				
			
		


Explicación

Endpoint: /homepage
Método: GET
Descripción: Retorna un saludo simple.

Salida del Programa
Al acceder a http://localhost:8080/homepage, la respuesta será:




		
		
			
			
Java
			
			homepage
			
				
					
				
					1
				
						homepage
					
				
			
		



Mejores Prácticas y Consideraciones de Seguridad
Almacenamiento Seguro de Secretos JWT
Asegúrate de que la clave secreta utilizada para firmar los JWT se almacene de manera segura y no se exponga en el código fuente. Utiliza variables de entorno o almacenes seguros.
Implementar Expiración de Tokens
Siempre establece un tiempo de expiración para los JWT para minimizar el riesgo de robo y uso indebido de tokens.
Usar HTTPS
Asegúrate de que todas las comunicaciones de la API ocurran sobre HTTPS para proteger los datos en tránsito.
Validar las Afirmaciones del Token
Siempre valida las afirmaciones dentro de los JWT, como emisor, audiencia y expiración, para asegurar la integridad del token.
Actualizar Regularmente las Dependencias
Mantén Swagger, las librerías de JWT y otras dependencias actualizadas para parchear vulnerabilidades conocidas.

Conclusión
Integrar Swagger y JWT en Spring Boot RESTful APIs mejora significativamente el proceso de desarrollo al proporcionar una documentación robusta y mecanismos de autenticación seguros. Swagger simplifica la exploración y prueba de APIs, mientras que JWT asegura una autenticación segura y sin estado adecuada para aplicaciones escalables. Siguiendo las pautas y mejores prácticas descritas en este eBook, los desarrolladores pueden construir APIs seguras y bien documentadas que satisfagan las necesidades actuales y futuras.
Palabras Clave: Swagger, JWT, Spring Boot, RESTful API, Documentación de API, JSON Web Token, Autenticación, Autorización, Springfox, Seguridad de API, OpenAPI, Microservicios, Autenticación sin Estado, APIs Seguras
Nota: Este artículo es generado por IA.