본문으로 건너뛰기

API 참조

이 페이지에서는 itdoc의 핵심 API에 대한 포괄적인 참조를 제공합니다.

핵심 함수​

describeAPI()​

API 엔드포인트를 정의하고 문서화하는 주요 함수입니다.

function describeAPI(
    method: HttpMethod,
    path: string,
    options: ApiDocOptions,
    app: Express.Application | any,
    testCallback: (apiDoc: RootBuilder) => void,
): void

매개변수:

  • method: API 엔드포인트의 HTTP 메소드 (GET, POST, PUT, DELETE 등)
  • path: API 엔드포인트의 URL 경로
  • options: 요약, 태그, 설명을 포함한 구성 옵션
  • app: 테스트할 Express 애플리케이션 인스턴스 또는 기타 애플리케이션
  • testCallback: 이 API 엔드포인트에 대한 테스트 케이스를 정의하는 콜백 함수

예시:

describeAPI(
    HttpMethod.GET,
    "/users",
    {
        summary: "모든 사용자 조회",
        tag: "사용자",
        description: "시스템의 모든 사용자 목록을 반환합니다",
    },
    app,
    (apiDoc) => {
        // 여기에 테스트 케이스 정의
    },
)

itDoc()​

describeAPI 블록 내에서 테스트 케이스를 정의합니다.

function itDoc(description: string, testFn: () => RootBuilder | Promise<RootBuilder>): void

매개변수:

  • description: 테스트 케이스에 대한 설명
  • testFn: 테스트를 정의하는 RootBuilder 인스턴스를 반환하는 함수

예시:

itDoc("성공적으로 모든 사용자를 검색합니다", () => {
    return apiDoc
        .test()
        .req()
        .queryParam({ page: 1, limit: 10 })
        .res()
        .status(HttpStatus.OK)
        .body({
            users: field("사용자 목록", [{ id: 1, name: "John" }]),
            total: field("총 개수", 1),
        })
})

field()​

문서화를 위해 요청 또는 응답 본문의 필드에 설명을 표시합니다.

function field<T>(description: string, value: T): T

매개변수:

  • description: 필드에 대한 설명
  • value: 테스트에서 사용할 필드 값

예시:

// 요청에서
.body({
  username: field('사용자 로그인 이름', 'john_doe'),
  password: field('사용자 비밀번호', 'securePassword123'),
})

// 응답에서
.body({
  id: field('사용자 ID', 123),
  token: field('인증 토큰', 'eyJhbGciOi...'),
})

열거형​

HttpMethod​

HTTP 메소드를 나타내는 열거형입니다.

enum HttpMethod {
    GET = "get",
    POST = "post",
    PUT = "put",
    DELETE = "delete",
    PATCH = "patch",
    HEAD = "head",
    OPTIONS = "options",
}

HttpStatus​

HTTP 상태 코드를 나타내는 열거형입니다.

enum HttpStatus {
    OK = 200,
    CREATED = 201,
    ACCEPTED = 202,
    NO_CONTENT = 204,
    MOVED_PERMANENTLY = 301,
    FOUND = 302,
    BAD_REQUEST = 400,
    UNAUTHORIZED = 401,
    FORBIDDEN = 403,
    NOT_FOUND = 404,
    METHOD_NOT_ALLOWED = 405,
    CONFLICT = 409,
    INTERNAL_SERVER_ERROR = 500,
    NOT_IMPLEMENTED = 501,
    BAD_GATEWAY = 502,
    SERVICE_UNAVAILABLE = 503,
    // ... (기타 상태 코드)
}

빌더 클래스​

RootBuilder​

API 테스트 케이스를 생성하기 위한 주요 빌더 클래스입니다.

주요 메소드:

  • test(): 새 테스트 케이스 초기화
  • req(): 요청을 구성하기 위한 RequestBuilder 반환
  • res(): 예상 응답을 구성하기 위한 ResponseBuilder 반환
  • prettyPrint(): 테스트 결과의 예쁜 출력 활성화

RequestBuilder​

테스트의 요청 부분을 구성하기 위한 빌더입니다.

주요 메소드:

  • body(body: object): 요청 본문 설정
  • header(headers: object): 요청 헤더 설정
  • pathParam(params: object): 경로 매개변수 설정
  • queryParam(params: object): 쿼리 매개변수 설정
  • expectStatus(status: HttpStatus): 예상 응답 상태 설정

ResponseBuilder​

테스트의 예상 응답 부분을 구성하기 위한 빌더입니다.

주요 메소드:

  • status(status: HttpStatus): 예상 응답 상태 코드 설정
  • body(body: object): 예상 응답 본문 설정
  • header(headers: object): 예상 응답 헤더 설정