---

📝 RESTful API 문서화

• RESTful API는 다른 개발자가 API 기능과 작동 방식을 쉽게 이해할 수 있도록 문서화가 필요합니다.

• 개발자가 혼자 쓰려고 만들더라도 문서는 필요합니다.

• 이번에는 OpenAPI 3를 이용하여:

  • 엔드포인트 목록
  • 허용되는 데이터 형식
  • API와 상호작용 방법
    등을 포함할 예정입니다.

---

📌 OpenAPI 3 기반 자동 문서 생성

• 이전에는 Swagger 명세라고 했습니다.
• 한국에서는 RAML보다는 OpenAPI를 더 많이 사용합니다.
• Spring Boot에서는 SpringDoc OpenAPI Starter WebMVC UI를 사용합니다.

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2'

💡 외부 라이브러리 사용 시 build.gradle dependencies에 추가가 필요합니다.

---

🔧 OpenAPI 설정 예제

com.example.cardatabase 패키지에 OpenApiConfig 클래스 생성:

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI carDatabaseOpenApi() {
        return new OpenAPI()
                .info(new Info()
                        .title("Car REST API")
                        .description("My car Stock")
                        .version("1.0")
                );
    }
}

• @Bean : 이 메서드에서 반환하는 객체를 Spring IoC 컨테이너가 관리하도록 등록
• new Info() 내부: 빌더 패턴과 메서드 체이닝 활용

---

⚙ application.properties 설정

spring.application.name=cardatabase
spring.datasource.url=jdbc:mariadb://localhost:3310/cardb
spring.datasource.username=root
spring.datasource.password=1234
spring.datasource.driver-class-name=org.mariadb.jdbc.Driver
spring.jpa.generate-ddl=true
spring.jpa.hibernate.ddl-auto=create-drop
spring.data.rest.basePath=/api
springdoc.swagger-ui.enabled=true
springdoc.swagger-ui.path=/swagger-ui.html
springdoc.api-docs.path=/api-docs

---

🟢 Spring Bean / @Bean

1️⃣ Bean이란?

• Spring IoC 컨테이너가 관리하는 객체
• Spring 이전: 개발자가 직접 객체 생성 → 의존성 관리 어려움
• Spring 이후: IoC 컨테이너에 객체 생성 위임 → 싱글톤으로 관리 가능

2️⃣ @Bean 애너테이션

• 메서드에 붙여서 반환 객체를 Spring 컨테이너에 등록
• 주로 @Configuration 클래스 안에서 사용

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI carDatabaseOpenApi() {
        return new OpenAPI()
                .info(new Info()
                        .title("Car REST API")
                        .description("My car Stock")
                        .version("1.0")
                );
    }
}

3️⃣ @Bean 사용 여부 비교

사용하지 않을 때

public class MyController {
    private MyService myService1 = new MyService();

    public void handleRequest() {
        myService1.doSomething();
    }
}

• 단점: 객체 간 결합도 ↑, 테스트 어려움, 유지보수 부담

사용했을 때

@Configuration
public class AppConfig {
    @Bean
    public MyService myService() {
        return new MyService();
    }
}

@Controller
public class MyController {
    private final MyService myService;

    public MyController(MyService myService) {
        this.myService = myService;
    }

    public void handleRequest() {
        myService.doSomething();
    }
}

• 장점: DI 적용, 객체 싱글톤 관리, 결합도 ↓, 테스트 용이

---

🔐 백엔드 보호

1️⃣ Spring Security 개요

• 기본 기능

  1. 인메모리 사용자 생성 (user / 콘솔 비밀번호)
  2. /css, /images 등 정적 리소스 접근 허용
  3. 기본 인증(HTTP Basic) 적용
  4. HSTS, XSS, CSRF 등 보안 기능 활성화
  5. 기본 로그인 페이지 제공

도입 방법

implementation 'org.springframework.boot:spring-boot-starter-security'
testImplementation 'org.springframework.boot:spring-boot-starter-security'

• Spring Security 적용 후 /login 페이지 자동 생성
• 테스트용 인메모리 사용자 제공

---

2️⃣ SecurityConfig 예제

@Configuration
@EnableWebSecurity
public class SecurityConfig {
    @Bean
    public InMemoryUserDetailsManager userDetailsService() {
        UserDetails user = User.builder()
                .username("user")
                .password(passwordEncoder().encode("password"))
                .roles("USER")
                .build();
        return new InMemoryUserDetailsManager(user);
    }

    @Bean
    public PasswordEncoder passwordEncoder(){
        return new BCryptPasswordEncoder();
    }
}

• @EnableWebSecurity : Spring Security 기본 보호 구성 해제 → 커스텀 가능
• PasswordEncoder : 비밀번호 암호화 (bcrypt)

---

3️⃣ DB 기반 사용자 인증

1. 엔티티 클래스 생성 (AppUser)

@Entity
@NoArgsConstructor(force = true)
@RequiredArgsConstructor
@Getter
@Setter
public class AppUser {
    @Id
    @GeneratedValue(strategy = GenerationType.AUTO)
    private Long id;

    @Column(nullable=false,unique=true)
    private final String username;

    @Column(nullable=false)
    private final String password;

    @Column(nullable=false)
    private final String role;
}

2. Repository 생성

@RepositoryRestResource(exported = false)
public interface AppUserRepository extends JpaRepository<AppUser, Long> {
    Optional<AppUser> findByUsername(String username);
}

• Optional : null 처리 안전하게 가능
• @RepositoryRestResource(exported = false) : REST 자동 노출 방지

3. UserDetailsService 구현

@Service
public class UserDetailsServiceImpl implements UserDetailsService {
    private final AppUserRepository userRepository;

    @Override
    public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException {
        Optional<AppUser> user = userRepository.findByUsername(username);
        if (user.isPresent()) {
            AppUser currentUser = user.get();
            return User.withUsername(username)
                       .password(currentUser.getPassword())
                       .roles(currentUser.getRole())
                       .build();
        } else {
            throw new UsernameNotFoundException("User not found");
        }
    }
}

• DB에서 사용자를 가져와 Spring Security 인증에 맞게 변환
• UserBuilder 활용, 인터페이스 강제 구현

4. SecurityConfig 수정 (DB 연동)

@Configuration
@EnableWebSecurity
public class SecurityConfig {
    private final UserDetailsServiceImpl userDetailsService;

    public SecurityConfig(UserDetailsServiceImpl userDetailsService) {
        this.userDetailsService = userDetailsService;
    }

    public void configGlobal(AuthenticationManagerBuilder auth) throws Exception {
        auth.userDetailsService(userDetailsService)
            .passwordEncoder(new BCryptPasswordEncoder());
    }

    @Bean
    public PasswordEncoder passwordEncoder(){
        return new BCryptPasswordEncoder();
    }
}

• 인메모리 사용자 → DB 기반 사용자로 변경
• 로그인 시 AppUser 테이블 정보 사용

---

🔑 Postman 테스트

• GET /api/cars → 인증 필요 → 401 Unauthorized
• POST 요청 시 Authorization 탭 → Basic Auth에 username/password 입력
• AppUser 테이블 확인 가능 (id, username, 암호화된 password)

---

💡 정리 포인트

1. OpenAPI 3 → RESTful API 자동 문서화
2. @Bean / Spring IoC → 객체 관리 및 DI
3. Spring Security → 인메모리 → DB 연동 인증
4. RepositoryRestResource → REST 노출 제어

---