Skip to content

openapi-usage.md

Latest commit

 

History

History
109 lines (82 loc) · 3.69 KB

openapi-usage.md

File metadata and controls

109 lines (82 loc) · 3.69 KB

OpenAPI Generated API 사용 가이드

이 문서는 src/api/openapi에 생성된 OpenAPI 클라이언트를 프로젝트에서 일관되게 사용하는 방법을 설명합니다.

정책 안내

  • src/api/openapi 하위의 파일은 OpenAPI Generator가 자동 생성합니다. 이 디렉터리의 코드를 직접 수정하지 마세요.
  • PR에서 해당 경로의 변경이 발견되면 CI가 실패하도록 설정되어 있습니다. 필요 변경이 있다면 래퍼/헬퍼 레이어에서 처리하거나, 백엔드 스펙 업데이트 후 재생성을 요청하세요.
  • 이 디렉터리는 ESLint와 Prettier 검사에서 자동으로 제외됩니다 (.eslintrc.cjs와 .prettierignore에 설정됨).

기본 원칙

  • Configuration으로 basePath를 지정합니다.
  • 각 API 클래스 생성자에 config와 config.basePath를 전달합니다.
  • 필요시 axiosInstance를 주입해 공통 인증 헤더, 에러 처리 로직을 재사용합니다.
  • 응답은 OpenAPI 타입(예: BaseResponseVoid, GroupStudyFullResponseDto)을 따릅니다.

실제 사용 예시

1. generateMetadata에서 공개 데이터 조회

import type { Metadata } from 'next';
import { GroupStudyManagementApi } from '@/api/openapi/api/group-study-management-api';
import { Configuration } from '@/api/openapi/configuration';
import type { GroupStudyFullResponseDto } from '@/api/openapi/models';

interface GroupStudyResponse {
  content?: GroupStudyFullResponseDto;
}

export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const { id } = await params;

  try {
    const config = new Configuration({
      basePath: process.env.NEXT_PUBLIC_API_BASE_URL,
    });

    const groupStudyApi = new GroupStudyManagementApi(config, config.basePath);

    const response = await groupStudyApi.getGroupStudy(Number(id));
    const groupStudy = (response.data as GroupStudyResponse)?.content;

    if (!groupStudy) {
      return {
        title: '그룹 스터디 - 제로원',
        description: '제로원 스터디 플랫폼에서 스터디를 둘러보세요.',
      };
    }

    const title = groupStudy.detailInfo?.title || '그룹 스터디';
    const description =
      groupStudy.detailInfo?.description ||
      groupStudy.detailInfo?.summary ||
      '제로원 스터디에 참여하세요.';

    return {
      title: `${title} - 제로원 스터디`,
      description,
      openGraph: {
        title: `${title} - 제로원 스터디`,
        description,
        images: groupStudy.detailInfo?.image?.resizedImages?.[0]
          ?.resizedImageUrl
          ? [groupStudy.detailInfo.image.resizedImages[0].resizedImageUrl]
          : [],
      },
    };
  } catch {
    return {
      title: '그룹 스터디 - 제로원',
      description: '제로원 스터디 플랫폼에서 스터디를 둘러보세요.',
    };
  }
}

환경변수 설정

Next.js 환경에서 올바른 엔드포인트로 요청하려면 NEXT_PUBLIC_API_BASE_URL이 필수입니다.

export NEXT_PUBLIC_API_BASE_URL=https://test-api.zeroone.it.kr
yarn run dev

환경변수가 누락되면 src/api/openapi/base.ts의 기본값으로 동작합니다.

타입 사용

OpenAPI로 자동 생성된 타입들:

// API 응답 타입
import type { GroupStudyFullResponseDto } from '@/api/openapi/models';
import type { BaseResponseVoid } from '@/api/openapi/models';

// Enum 타입
import { GetGroupStudiesGroupStudyStatusEnum } from '@/api/openapi/api/group-study-management-api';

// 사용 예
const status = GetGroupStudiesGroupStudyStatusEnum.Recruiting;

참고 문서

  • src/api/openapi/docs/ : 각 API별 상세 문서
  • src/api/openapi/models/ : 자동 생성된 타입 정의