S02L01 - Spring Boot RestApi，JWT 演示

html

在 Spring Boot RESTful API 中集成 Swagger 和 JWT：全面指南

目录

介绍
了解 Swagger
JWT（JSON Web Tokens）简介
在 Spring Boot 中设置 Swagger
实现 JWT 认证
自定义 Swagger UI
使用 Swagger 测试 API
最佳实践和安全注意事项
结论


介绍
在现代 Web 开发领域，创建安全且文档完善的 APIs 至关重要。本电子书深入探讨了在 Spring Boot RESTful APIs 中集成 Swagger 和 JWT (JSON Web Tokens) 的方法。通过利用 Swagger 进行 API 文档编制和 JWT 进行认证，开发人员可以构建强大、安全且易于维护的应用程序。本指南针对初学者和具备基本知识的开发人员，提供清晰简洁的说明和实用示例。

了解 Swagger
什么是 Swagger？
Swagger 是一个开源框架，帮助设计、构建、文档编制和使用 RESTful Web 服务。它提供了一个用户友好的界面，可以在不涉及任何实现逻辑的情况下可视化和交互 API 的资源。
Swagger 的主要功能

API 文档：自动生成交互式文档。
API 测试：方便地直接从 UI 测试端点。
Schema 定义：定义请求和响应的数据模型和结构。

Swagger 在 API 开发中的重要性
Swagger 通过提供清晰的文档，提升了开发工作流程，这对于协作和维护至关重要。它简化了理解 API 端点及其功能的过程。

JWT（JSON Web Tokens）简介
什么是 JWT？
JWT (JSON Web Token) 是一种紧凑、URL 安全的表示声明的方式，用于在两方之间传输。它在 Web 应用程序中广泛用于认证和授权。
JWT 的关键组件

Header：包含有关令牌的元数据，包括类型和签名算法。
Payload：包含关于用户或实体的声明或语句。
Signature：通过验证令牌未被篡改来确保其完整性。

使用 JWT 的优势

无状态认证：消除了服务器端会话的需求。
可扩展性：适用于分布式系统和微服务。
安全性：以安全的方式编码用户信息，并带有过期时间。


在 Spring Boot 中设置 Swagger
前提条件

基本的 Spring Boot 知识。
安装了 Java Development Kit (JDK)。
Maven 或 Gradle 构建工具。

逐步集成

添加 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>
					
				
			
		


配置 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();
    }
}
					
				
			
		


访问 Swagger UI
启动 Spring Boot 应用程序并导航至 http://localhost:8080/swagger-ui/ 查看交互式 API 文档。

实现 JWT 认证
为什么使用 JWT？
JWT 提供了一种在无状态应用程序中处理认证和授权的安全高效方式。它确保每个请求都经过认证，而无需维护服务器端会话。
在 Spring Boot 中设置 JWT

添加 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>
					
				
			
		


创建 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));
    }
}
					
				
			
		


创建认证控制器




		
		
			
			
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) {
        // Authenticate user
        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 and 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) {
        // Authenticate user
        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 and 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;
    }
}
					
				
			
		



自定义 Swagger UI
更新应用信息
您可以使用特定于应用程序的详细信息（如名称、版本和描述）来自定义 Swagger UI。




		
		
			
			
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",
            "服务条款",
            new Contact("Your Name", "www.example.com", "you@example.com"),
            "API 许可",
            "API 许可 URL",
            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",
            "服务条款",
            new Contact("Your Name", "www.example.com", "[email protected]"),
            "API 许可",
            "API 许可 URL",
            Collections.emptyList());
}
					
				
			
		


向 Swagger 添加授权
Swagger UI 允许向 API 请求添加授权头，从而启用经过认证的测试。

配置安全方案





		
		
			
			
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");
}
					
				
			
		


使用 JWT 授权

点击 Swagger UI 中的 "Authorize" 按钮。
输入以 Bearer  为前缀的 JWT 令牌（例如 Bearer your_jwt_token）。
授权后，Swagger 将在后续的 API 请求中包含该令牌。


使用 Swagger 测试 API
进行认证请求

生成 JWT 令牌

使用带有有效凭据的 /token 端点接收 JWT。

授权 Swagger UI

点击 "Authorize" 并按照前述方式输入令牌。

访问受保护的端点

设置了授权后，您现在可以直接从 Swagger UI 访问受保护的 APIs。


示例程序代码




		
		
			
			
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";
    }
}
					
				
			
		


解释

端点：/homepage
方法：GET
描述：返回一个简单的问候语。

程序输出
访问 http://localhost:8080/homepage 时，响应将是：




		
		
			
			
Java
			
			homepage
			
				
					
				
					1
				
						homepage
					
				
			
		



最佳实践和安全注意事项
安全存储 JWT 密钥
确保用于签署 JWT 的密钥安全存储，不要在代码库中暴露。使用环境变量或安全的密钥库。
实现令牌过期
始终为 JWT 设置过期时间，以最小化令牌被盗用和滥用的风险。
使用 HTTPS
确保所有 API 通信通过 HTTPS 进行，以保护传输中的数据。
验证令牌声明
始终验证 JWT 中的声明，如发布者、受众和过期时间，以确保令牌的完整性。
定期更新依赖项
保持 Swagger、JWT 库和其他依赖项的最新，以修补已知漏洞。

结论
将 Swagger 和 JWT 集成到 Spring Boot RESTful APIs 中，显著提升了开发流程，提供了强大的文档和安全的认证机制。Swagger 简化了 API 的探索和测试，而 JWT 确保了适用于可扩展应用程序的安全、无状态认证。通过遵循本电子书中概述的指南和最佳实践，开发人员可以构建满足当前和未来需求的安全、文档完善的 APIs。
关键词：Swagger, JWT, Spring Boot, RESTful API, API Documentation, JSON Web Token, Authentication, Authorization, Springfox, API Security, OpenAPI, Microservices, Stateless Authentication, Secure APIs
注意：本文由 AI 生成。