초보 개발자도 쉽게 이해하는 API 명세서 작성 가이드: 회원가입 API 완벽 분석

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 클래스를 가져온 후 반환 타입만 지정해주면 코드 작성 완료 입니다.