S02L01 - 스프링 부트 REST API, JWT 데모

html

Spring Boot RESTful API에서 Swagger와 JWT 통합: 종합 가이드

목차

소개
Swagger 이해하기
JWT (JSON Web Tokens) 소개
Spring Boot에서 Swagger 설정하기
JWT 인증 구현
Swagger UI 사용자 지정
Swagger로 API 테스트하기
모범 사례 및 보안 고려 사항
결론


소개
현대 웹 개발 분야에서 안전하고 잘 문서화된 API를 만드는 것은 매우 중요합니다. 이 전자책은 Swagger와 JWT (JSON Web Tokens)를 Spring Boot RESTful API에 통합하는 방법을 자세히 다룹니다. API 문서화를 위해 Swagger를 활용하고 인증을 위해 JWT를 사용함으로써, 개발자들은 견고하고 안전하며 유지 관리가 용이한 애플리케이션을 구축할 수 있습니다. 이 가이드는 초보자와 기본 지식을 가진 개발자를 위해 맞춤화되어 있으며, 명확하고 간결한 지침과 실용적인 예제를 제공합니다.

Swagger 이해하기
Swagger란 무엇인가?
Swagger는 RESTful 웹 서비스를 설계, 구축, 문서화 및 소비하는 데 도움을 주는 오픈 소스 프레임워크입니다. 구현 로직 없이 API의 리소스를 시각화하고 상호 작용할 수 있는 사용자 친화적인 인터페이스를 제공합니다.
Swagger의 주요 기능

API 문서화: 자동으로 대화형 문서를 생성합니다.
API 테스트: UI에서 직접 엔드포인트를 테스트할 수 있도록 도와줍니다.
스키마 정의: 요청 및 응답을 위한 데이터 모델과 구조를 정의합니다.

API 개발에서 Swagger의 중요성
Swagger는 명확한 문서를 제공하여 협업과 유지 관리를 용이하게 함으로써 개발 워크플로우를 향상시킵니다. API 엔드포인트와 그 기능을 이해하는 과정을 단순화합니다.

JWT (JSON Web Tokens) 소개
JWT란 무엇인가?
JWT (JSON Web Token)은 두 당사자 간에 전송될 클레임을 표현하는 컴팩트하고 URL-안전한 수단입니다. 웹 애플리케이션에서 인증 및 권한 부여에 널리 사용됩니다.
JWT의 주요 구성 요소

헤더: 토큰의 유형과 서명 알고리즘을 포함하는 메타데이터를 담고 있습니다.
페이로드: 사용자 또는 엔티티에 대한 클레임 또는 진술을 담고 있습니다.
서명: 토큰이 변경되지 않았음을 검증하여 토큰의 무결성을 보장합니다.

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) {
        // 사용자 인증
        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) {
        // 사용자 인증
        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에서 직접 보안된 API에 접근할 수 있습니다.


샘플 프로그램 코드




		
		
			
			
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 API에 통합함으로써 견고한 문서화와 안전한 인증 메커니즘을 제공하여 개발 프로세스를 크게 향상시킬 수 있습니다. Swagger는 API 탐색 및 테스트를 단순화하고, JWT는 확장 가능한 애플리케이션에 적합한 안전하고 무상태 인증을 보장합니다. 이 전자책에 설명된 지침과 모범 사례를 따르면 개발자들은 현재와 미래의 요구를 충족하는 안전하고 잘 문서화된 API를 구축할 수 있습니다.
키워드: Swagger, JWT, Spring Boot, RESTful API, API Documentation, JSON Web Token, Authentication, Authorization, Springfox, API Security, OpenAPI, Microservices, Stateless Authentication, Secure APIs
참고: 이 기사는 AI에 의해 생성되었습니다.