Postman + OpenAPI로 타입 체크되는 API 만들기

프로젝트를 진행하다 보면 이런 문제가 발생한다.

• API 경로를 잘못 입력해서 발생하는 휴먼 에러
• API를 만들 때마다 반복되는 타입 지정
• 반복되는 작업을 최대한 줄이고 싶은 상황

Postman에서 API를 자동으로 타입화하고 리팩토링하는 과정을 정리해봤다.

1. Postman JSON → OpenAPI YML 변환

먼저 postman-to-openapi 라이브러리를 설치한다.

npm install -g postman-to-openapi

 

그 다음 아래 명령어로 JSON 파일을 YML 파일로 변환한다.

p2o ./path/to/PostmanCollection.json -f ./path/to/result.yml -o ./path/to/options.json

 

변환 결과는 API 경로, 요청 파라미터, 응답 형식이 정리된 YML 파일로 출력된다.

						"url": {
// postman json							
"raw": "{{dev}}/api/oauth2/login",
        "host": [
            "{{dev}}"
        ],
        "path": [
            "api",
            "oauth2",
            "login"
        ]
    },
    "description": "## API path\n\n- /api/oauth2/login\n    \n\n## Request\n\n### Request parameter\n\n| **ield** | **type** | **required** | description |\n| --- | --- | --- | --- |\n| provider | string | O | KAKAO  <br>APPLE |\n| authorizationCode | string | O | 소셜 로그인 인증 코드 |\n\n---\n\n## Response\n\n### Success (Httpstatus code: 200)\n\n### Response body\n\n| **field** | **type** | **description** |\n| --- | --- | --- |\n| grantType | string | 토큰 타입 |\n| accessToken | string | 사용자 액세스 토큰 |\n| refreshToken | string | 사용자 리프레시 토큰 |\n\n### Cookie\n\n| **field** | **type** | **description** |\n| --- | --- | --- |\n| accessToken | string | 사용자 액세스 토큰 |\n| refreshToken | string | 사용자 리프레시 토큰 |"
},
"response": []

// .yaml 
/api/oauth2/login:
  post:
    tags:
      - OAuth
    summary: 토큰 발급
    description: |-
      ## API path
      - /api/oauth2/login

      ## Request
      ### Request parameter
      | **field** | **type** | **required** | description |
      | --- | --- | --- | --- |
      | provider | string | O | KAKAO  <br>APPLE |
      | authorizationCode | string | O | 소셜 로그인 인증 코드 |

      ---
      ## Response
      ### Success (Httpstatus code: 200)
      ### Response body
      | **field** | **type** | **description** |
      | --- | --- | --- |
      | grantType | string | 토큰 타입 |
      | accessToken | string | 사용자 액세스 토큰 |
      | refreshToken | string | 사용자 리프레시 토큰 |

 

참고로, 위 단계는 API 구조를 기계가 읽을 수 있는 형태로 만들어, 다음 단계에서 타입을 자동 생성할 수 있도록 준비하는 과정이다.

 

2. OpenAPI YML → TypeScript 타입 생성

왜 필요한가?

YML 파일에는 API 경로, 요청 파라미터, 응답 구조가 정리되어 있지만, 실제 코드에서 타입 안정성을 확보하려면 TypeScript 타입이 필요하다.

수동으로 타입을 만들면 휴먼 에러가 발생하기 쉽고, 유지보수도 어렵다.

따라서 OpenAPI YML을 TypeScript 타입으로 자동 변환하면 모든 API 요청과 응답을 타입 체크 가능하게 만들 수 있다.

TypeScript 타입 생성

openapi-typescript 라이브러리를 설치한다.

npm install openapi-typescript --save-dev

 

YML 파일에서 TypeScript 타입을 자동 생성한다.

openapi-typescript ./result.yml -o ./app/__generated__/api.ts

 

실제 결과 api.ts 파일

    "/api/finance/pt/curriculum/{curriculumId}/step/{stepId}/todo": {
        parameters: {
            query?: never;
            header?: never;
            path?: never;
            cookie?: never;
        };
        /** 할 일 목록 조회 */
        get: {
            parameters: {
                query?: never;
                header?: never;
                path: {
                    /** @example 93ddbe02-9c17-11f0-9fd6-1d9aad96e7c3 */
                    curriculumId: string;
                    /** @example 93e235a4-9c17-11f0-9fd6-1d9aad96e7c3 */
                    stepId: string;
                };
                cookie?: never;
            };
            requestBody?: never;
            responses: {
                /** @description OK */

 

결과

아래처럼 입력하면 모든 api가 불러와지는 것을 볼 수 있고 parameter 들에 대한 타입까지 다 지정되어있어서 타입체크가 되는 것을 확인할 수 있다.

 

결론

Postman 컬렉션을 OpenAPI(YML)로 변환한 뒤, openapi-typescript를 사용해 TypeScript 타입을 자동 생성해보았다. 이 과정을 통해 기존에 반복적으로 작성하던 API 파라미터와 응답 구조를 자동으로 타입화할 수 있었고, 프론트엔드에서 안전하게 API를 호출할 수 있게 되었지만, Postman에서 API가 명확하게 지정되지 않은 경우에는 제대로 타입이 생성되지 않는다는 단점도 있었다.

또한 OpenAPI Generator와 같은 라이브러리가 어떤 단계를 거쳐 API 코드를 생성하는지 궁금했는데, 단계를 직접 쪼개서 구현해보면서 그 원리를 조금 더 이해할 수 있었다.