ABOUT ME

-

Today
-
Yesterday
-
Total
-
  • 초보 개발자도 쉽게 이해하는 API 명세서 작성 가이드: 회원가입 API 완벽 분석
    🌱 Spring 프레임워크 2025. 1. 5. 15:58
    728x90

    API 명세서를 기준으로 연습 및 설명이 진행 되며, 필요에 의해 클래스 생성이 진행될 예정이다보니 순서가 왔다갔다 할 예정입니다.

     

    API 명세서  - 회원가입

    더보기

    이 API는 새로운 사용자를 시스템에 등록합니다.

    URL: /api/v1/users/signup

    Method: POST

    설명:

    • 새로운 사용자를 시스템에 등록합니다.
    • 이메일 중복 확인을 수행합니다.
    • 비밀번호는 암호화하여 저장됩니다.
    • 기본 사용자 권한(USER)으로 생성됩니다.

    Request Body:

    JSON
     
    {
      "email": "user@example.com",
      "password": "password123",
      "nickname": "사용자닉네임"
    }
    

     

    Validation:

    • email: 유효한 이메일 형식 (@ 포함)
    • password: 최소 8자 이상, 영문/숫자/특수문자 조합
    • nickname: 2-20자 이내, 한글/영문/숫자 허용

    Response:

    • 201 Created: 성공적으로 사용자가 생성됨

    예시:

    Request:

     

    Response:

    HTTP/1.1 201 Created
    Location: /api/v1/users/12345

     

    공통 사항

    1. 에러 처리

    주요 에러 상황:

    • 400 Bad Request: 잘못된 요청 파라미터
    • 401 Unauthorized: 인증 실패 또는 토큰 만료
    • 403 Forbidden: 권한 없음
    • 404 Not Found: 리소스를 찾을 수 없음
    • 409 Conflict: 데이터 충돌 (예: 이메일 중복)
    • 500 Internal Server Error: 서버 오류

    2. 페이징 처리

    페이징이 적용된 모든 API는 다음 정보를 포함합니다:

    • page: 현재 페이지 번호 (1부터 시작)
    • size: 페이지당 항목 수
    • totalElements: 전체 데이터 수
    • totalPages: 전체 페이지 수

    3. 인증

    • Bearer 토큰 방식의 JWT 인증을 사용합니다.
    • 인증이 필요한 API의 경우 반드시 Authorization 헤더에 토큰을 포함해야 합니다.

    4. API 버전 관리

    • URI의 /api/v1 prefix로 API 버전을 관리합니다.
    • 향후 하위 호환성이 깨지는 변경사항이 있을 경우 버전이 변경될 수 있습니다.

     

     

     

    사용된 의존성 

     

    • Spring Web: 웹 애플리케이션 개발에 필요한 Spring MVC, 내장 Tomcat 서버 등을 포함합니다. RESTful API 개발에 필수적인 의존성입니다.
    • Spring Security: Spring 애플리케이션의 보안 (인증, 권한 부여 등)을 담당하는 프레임워크입니다.
    • Spring Data JDBC: JDBC를 사용하여 SQL 데이터베이스에 접근하고 데이터를 관리할 수 있도록 지원하는 라이브러리입니다.
    • MySQL Driver: MySQL 데이터베이스를 사용하기 위한 JDBC 드라이버입니다.
    • Lombok: 반복적인 코드 작성을 줄여주는 자바 어노테이션 라이브러리입니다.

     

     

    포스트맨으로 리퀘스트 생성하기

    • HTTP 메서드 설정: 회원가입 API는 POST 메서드를 사용하므로, 드롭다운 메뉴에서 POST를 선택합니다.
    • URL 입력: 회원가입 API의 URL을 입력합니다. 예시에서는 /api/v1/users/signup 을 사용합니다.
    • Body 탭 선택: Body 탭을 선택하고, raw를 선택한 후 JSON 형식으로 요청 데이터를 입력합니다.

     

    엔티티  User 클래스 생성

    entity 패키지에 User 엔티티 클래스를 생성합니다.

     

    • @NoArgsConstructor: 파라미터가 없는 기본 생성자를 자동으로 만들어줍니다.
    • @AllArgsConstructor: 모든 필드를 파라미터로 받는 생성자를 자동으로 만들어줍니다.
    • @Data: @Getter, @Setter, @ToString, @EqualsAndHashCode 등을 한 번에 적용하여 getter/setter, toString, equals, hashCode 메서드를 자동으로 생성해줍니다.

    컨트롤러 클래스 생성

    controller 패키지에 UserController 클래스를 생성합니다.

    코드 작성

    @PostMapping("/api/v1/users/signup")
    signup(@RequestBody UserRequest userRequest) {

     

     

    UserRequest 정보를 받아와야 하는데 클래스가 없으니 생성하러 이동합니다.  

     

    생성을 완료 했으니 UserController 클래스 코드 작성을 진행 하러 갑니다.

    @PostMapping("/api/v1/users/signup")
        signup(@RequestBody UserRequest userRequest) {
            // 회원가입을 진행 하기 위해 클라이언트가 보낸 user 정보를 받아서 userService.signup() 메소드를 호출한다.
            userService.signup(userRequest);

     

    userService 에 일 시켜야 하는데 없으니 생성한 후 메소드 작성 합니다.

    UserDao.signup 메소드를 작성하기 위해 클래스 생성합니다.

     

    SQL 문 작성을 위해 디비버 접속 후 SQL문 작성합니다.

    INSERT INTO users (email, password , nickname , role ) values ('asda11144111@gmail.com', '123ddWd@#4da' , '연습용' , 'user' );

     

    정상적으로 작동이 잘 되는것을 확인 했으니 코드에 적용 해줍니다.

     

    DAO 작성이 완료되었으니 Service 클래스로 이동 하여 마무리 해 주도록 하겠습니다.

    서비스도 작성이 끝났으니 Controller 에서 마지막 코드만 작성 합니다.

     

    마지막으로 ResponseEntity 클래스를 가져온 후 반환 타입만 지정해주면 코드 작성 완료 입니다.

     

     

     

     

    728x90
Designed by Tistory.