[코드잇 스프린트] 고급 프로젝트 (메인 페이지 API)

이언덕·2025년 6월 21일

코드잇 스프린트 프로젝트

목록 보기

13/24

🔧 API 연결 삽질기와 해결법

🧭 먼저 구조 파악부터: Swagger와 타입 정의 파일

아래는 swagger에서 체험 리스트 조회 API를 호출하는 화면이다.

화면을 참고해 다음과 같은 쿼리 파라미터들을 확인할 수 있었다.

teamId (path): 팀 식별자 (우리는 14기 4팀이기 때문에 14-4가 고정적이다!)

method: offset 또는 cursor 방식 선택

cursorId: 커서 방식일 경우 기준 ID

category: 카테고리 필터

keyword: 검색 키워드

sort: 정렬 기준 (e.g., most_reviewed, price_asc, latest 등)

page: 페이지 번호

size: 한 페이지에 담을 항목 수

이 정보는 실제 프로젝트의 activity.schema.ts에도 아래와 같이 정의돼 있다.
export interface GetActivityListPayloadType {
  query: {
    method: "offset" | "cursor";
    cursorId?: number;
    category?: ActivityCategoryType;
    keyword?: string;
    sort?: "most_reviewed" | "price_asc" | "price_desc" | "latest";
    page?: number;
    size?: number;
  };
}

📁 팀원이 미리 잘 정리해둔 API 함수

프로젝트에 들어가 보니 activity.service.ts 파일에 이미 모든 API 함수들이 정리되어 있었다.
그래서 내가 직접 axios 요청 코드를 짜는 게 아니라, 서비스 모듈에서 제공하는 함수만 가져다 쓰면 됐다.
예를 들면 아래와 같다:
/**
 * 체험 리스트 조회
 *
 * @property {number} page - 기본 값: 1
 * @property {number} size - 기본 값: 20
 */
getActivities({
  query,
  options,
}: ApiRequestParams<GetActivityListPayloadType>) {
  return this.fetcher<GetActivityListResultType>({
    url: "/activities",
    method: HTTP_METHODS.GET,
    params: query,
    ...options,
  });
}

❌ 잘못된 API 함수 연결로 한참을 헤맨 이유

메인페이지에 체험 리스트를 렌더링하려고 API 연결을 시도했는데, 계속 오류가 발생해서 디버깅에 시간을 많이 썼다.
결국 문제는 잘못된 API 함수 사용이었다.
// ❌ 내가 실수로 사용한 API
getActivity({ activityId }) 
// → 특정 체험 하나의 상세 정보를 가져오는 함수
--------------------------------------
// ✅ 실제로 사용해야 했던 API
getActivities({ query }) 
// → 여러 체험을 리스트 형식으로 가져오는 함수
이런 실수가 생긴 이유는, 단순히 함수 이름만 보고 "이거겠지?" 하고 사용했기 때문이다.
페이지의 목적과 API의 구조를 제대로 파악하지 않고 연결하려다 보니 생긴 문제였다.

🔗 실제로 연결한 체험 리스트 API (getActivities)

아래는 실제 메인페이지(page.tsx)에서 체험 리스트를 렌더링하는 코드 일부다. (배너와 모든 체험에서 사용되어졌다.)

useEffect(() => {
  const fetchActivities = async () => {
    try {
      // 🔗 체험 리스트 조회 API 연결: getActivities 함수 사용
      const response = await activityService.getActivities({
        query: {
          method: "offset",
          category: selectedCategory || undefined,
          sort: sortOption.id,
          page: currentPage,
          size: itemsPerPage,
        },
      });
      setActivities(response.data.activities);
      setTotalPages(Math.ceil(response.data.totalCount / itemsPerPage));
    } catch (error) {
      console.error("Error fetching activities:", error);
    }
  };
  fetchActivities();
}, [selectedCategory, currentPage, sortOption, itemsPerPage]);

그리고 이렇게 받아온 데이터는 아래처럼 .map() 함수로 리스트를 구성해 렌더링했다

<div className="grid grid-cols-2 tablet:grid-cols-2 desktop:grid-cols-4 gap-4">
  {activities?.map((activity) => (
    <Card
      key={activity.id}
      title={activity.title}
      price={activity.price}
      bannerImageUrl={activity.bannerImageUrl}
      rating={activity.rating}
      reviewCount={activity.reviewCount}
    />
  ))}
</div>

페이지를 보면 모든 체험과 배너에 체험이 잘 보여진다.

🔥 인기 체험 API도 동일한 방식으로 처리

useEffect(() => {
  const fetchPopularActivities = async () => {
    try {
      // 🔗 인기 체험 리스트 조회에도 동일한 getActivities 함수 사용 (sort: most_reviewed)
      const response = await activityService.getActivities({
        query: {
          method: "offset",
          sort: "most_reviewed",
        },
      });
      setPopularActivities(response.data.activities);
    } catch (error) {
      console.error("Error fetching popular activities:", error);
    }
  };
  fetchPopularActivities();
}, []);

(인기 체험 API 동기화 함수를 따로 만든 이유는?
➡️ 인기 체험에서는 별점 리뷰순으로 정렬이 되어서 보여지기 때문에 API 동기화 함수를 따로 만들게 되었다.)
인기 체험도 마찬가지로 .map() 함수를 사용해 아래처럼 카드 형태로 렌더링했다:

<div className="grid tablet:grid-cols-2 desktop:grid-cols-4 gap-4 hidden mobile:hidden tablet:grid">
  {paginatedActivities?.map((activity) => (
    <Card
      key={activity.id}
      title={activity.title}
      price={activity.price}
      bannerImageUrl={activity.bannerImageUrl}
      rating={activity.rating}
      reviewCount={activity.reviewCount}
    />
  ))}
</div>

페이지를 보면 인기 체험이 잘 보여진다.

🚧 삽질을 줄이기 위한 교훈

API 이름만 믿지 말고 실제 리턴 데이터 확인할 것.

페이지에 필요한 데이터의 구조와 흐름을 먼저 파악하고 API를 연결할 것.

활용 예시는 swagger나 기존 사용 코드에서 충분히 참고할 것.

🚀 체험 등록 전체 흐름 정리 (Swagger 활용)

API를 연동하고 체험 카드를 테스트 하기 위해선 직접 체험 데이터를 등록해야 했다.
그래서 최종적으로 다 잘 돼보는 체험 등록 절차를 쭉 정리해보는 게 이 포스팅의 목적!

1️⃣ 회원가입 먼저 하기

회원가입에서는 위 사진과 같이 Try it out을 눌러야 회원가입을 할 수 있고, 모든 swagger에서 테스트를 하려면 Try it out 버튼을 눌러야만 테스트 할 수 있다.

Try it out 버튼을 누르게 되면 Request body가 작성 가능한 상태로 아래 사진처럼 활성화된다.

그 다음엔 teamId와 함께 JSON 양식에 맞춰 아래처럼 작성해준다.

Execute 버튼을 누르면 아래와 같이 Response로 회원가입이 정상 처리된다.

회원가입 API를 통해 아이디와 비밀번호를 먼저 등록해줘야 한다.
이건 왜 중요하냐면, 로그인을 통해 토큰을 발급받아야 이후 인증이 가능하기 때문!

2️⃣ 로그인해서 엑세스 토큰 받기

로그인쪽에 가서 Try it out 버튼을 누르고, 이전에 가입한 아이디/비밀번호를 입력한 뒤 Execute 버튼을 누른다.

정상적으로 201 Response가 오고 Response body에 엑세스 토큰이 발급된 것을 확인할 수 있다.
이 토큰은 나중에 swagger에 인증할 때 꼭 필요하다.

💡 추가 팁: 이 토큰은 일정 시간이 지나면 만료되므로, 장시간 작업 시엔 갱신이 필요하다.

3️⃣ Swagger 인증 (Authorize)

swagger 오른쪽 위의 Authorize 버튼을 클릭하면 아래와 같은 입력창이 뜬다.

여기에 토큰을 붙여넣고 확인하면,

자물쇠 아이콘이 잠긴 상태로 바뀐다.
여기서 인증을 해줘야 체험 등록 같은 protected API들이 동작한다!

4️⃣ 이미지 URL 만들기

체험 등록 시 필요한 카드 이미지는 피그마에서 미리 다운로드한 뒤,
S3 같은 외부 저장소를 통해 URL로 변환해줘야 한다.

체험 이미지 url 생성에 가서 Try it out 버튼을 누르고 이미지를 첨부하면

위처럼 Response body에 이미지 URL이 생성되어 반환된다.
직접 업로드한 이미지 URL을 bannerImageUrl 필드에 넣어야 체험 등록이 제대로 된다.

5️⃣ 체험 등록 JSON으로 등록하기

체험 등록에 가서 Try it out을 눌러 활성화 시키면 아래와 같은 Request body를 보낼 수 있다.
아래는 예시이기 때문에 직접 내용을 작성해 등록하면 된다.

체험을 만들어 Execute를 눌러 Request를 보내게 되면,

Response body로 내가 만든 체험이 성공적으로 오는 것을 볼 수 있다.

6️⃣ 체험 리스트로 등록 확인

위에서 만든 체험등록이 잘 생성됐는지 확인해 보자.

체험 리스트에 가서 teamId를 입력해주고 Execute를 눌러주면 체험 리스트들을 볼 수 있다.

Response body로 가서 체험 리스트들을 보면 제일 최근에 생성된 체험들 중 내가 만든 체험을 확인할 수 있다.
정상적으로 등록되었으면, 바로 프론트에서 렌더링 테스트에 사용할 수 있다.
(아래 내가 만든 체험이 페이지에 렌더링 되는 것을 볼 수 있다.)

✅ 정리

회원가입 → 로그인 → 인증 → 이미지 업로드 → JSON 작성 → 등록 → 확인 순서로 진행

swagger에서 전체 테스트 가능

이미지 업로드부터 URL 생성까지도 swagger에서 완료 가능