swagger-typescript-api 사용법 (axios, CORS, reverse-proxy-server)

이제 BFF서버에서 api를 하나 둘 제공하고 있다. 더이상 mockAPI에서 실제 api로 교체할 타이밍이다. api는 swagger를 통해 제공된다.

따라서 이번엔 swagger-typescript-api 라는 라이브러리에 대해 알아보자

swagger-typescript-api

이는 TS환경에서 API문서(OpenAPI사양의 문서)를 통해 자동으로 api를 생성하고 타입 추론까지 자동화 해주는 정말 편한 라이브러리이다. swagger또한 OpenAPI문서이기 때문에 이 라이브러리를 사용할 수 있다.

적용

//package.json
"scripts": {
	...,
 	"api": "swagger-typescript-api -p {OpenAPI문서url} -o ./src -n api.ts"
}

라이브러리가 문서 경로를 지정하고, 저장될 위치에 api.ts이름으로 생성한다는 의미이다.

axios의 적용

//package.json
"scripts": {
	...,
 	"api": "swagger-typescript-api -p {OpenAPI문서url} -o ./src -n api.ts --axios"
}
//추가적인 스크립트 명령어는 swagger-typescript-api에서 확인해라

axios는 자동으로 응답을 JSON으로 변환해서 기존 fetch()와 달리 더 짧은 코드로 작성할 수 있고, baseURL설정, 인터셉터 기능 등 편리한 점을 많이 지원해서 axios를 선호한다.

axios 설명

const api = axios.create({
	baseURL : 지정할domainURL
}) // Axios 인스턴스 생성

api.get(url).then()
api.get(url,{
	params: {
    	...
    }
}).then()
api.post(url, {
	body로 보낼 데이터
}).then()

// 인터셉터 기능
api.interceptors.request.use((config) => {
    config.headers.Authorization = `access token`;
    console.log('리퀘스트 인터셉터는 엑세스 토큰 체크 또는 인증 체크를 할 때 사용한다.', config)
    return config
})

api.interceptors.response.use((res) => {
    console.log('리스폰스 인터셉터는 응답 데이터를 가공할 때 사용한다.',res)
    // if(res.status === 200){
    //     throw new Error('에러났다~')
    // }
    return res
})

axios 인스턴스 생성으로 기본URL설정, 일관성유지, 인스턴스별 설정, 코드 재사용성 등 장점이 많고, HTTP메서드가 굉장히 간소화되고 예를 들어 post요청에 header, body속성을 따로 기입하지 않고 간결하게 코드를 작성할 수 있다.

무엇보다 interceptors를 통해 클라이언트(axios)와 서버 통신 사이에서 추가적인 로직을 진행할 수 있다

api-generator 사용

pnpm api를 통해 ./src에 api.ts가 생성되었을 것이다. 그 파일 안에는 모든 api의 타입이 지정되어있고 api엔드포인트가 함수화 되어있다.

import {Api} from './api'

const api = new Api({
	baseURL: 내 로컬 url
})

이제 api객체에 엔드포인트들을 호출해서 사용하면 된다.
axios기반으로 설정된 api인스턴스라 baseURL을 추가했다.

CORS에러

당연하게도 다른 출처(도메인)의 리소스에 접근할 때 브라우저는 CORS 에러를 발생시킨다.
내가 baseURL을 클라이언트의 로컬 url로 설정한 이유가 있다.
api의 도메인을 로컬도메인으로 우회해야한다.

그럼 어떻게 우회를 하는가? 정답은 reverse-proxy-server의 개념을 사용한다

reverse-proxy-server란?

클라이언트와 서버사이에 존재하며 각 요청을 전달하는 중개역할의 서버라고 보면 된다.
이 개념을 이번 주제에서 CORS해결을 위해 요청받는 도메인 주소를 클라이언트의 도메인 주소로 바꿔보내고, 리버스 프록시 설정에서 도메인의 타겟을(실제 api도메인) 설정해주면 CORS를 해결할 수 있다.

적용

어떤 빌드툴을 사용하는지에 따라 설정방법은 달라진다. 나는 vite에서 진행했다.

// vite.config.ts


export default defineConfig({
  plugins: [react()],
  server: { // 리버스 프록시 세팅
    proxy: {
      'API경로(엔드포인트)' : {
        target: api도메인URL, // 타겟 도메인(실제 api 도메인주소, 환경변수사용권장)
        changeOrigin: true  // origin 변경
      }
    }
  }
})

//예시
proxy: {
  '/api': {
    target: 'https://api.example.com',
    changeOrigin: true,
    rewrite: (path) => {
      return path.replace(/^\/api/, '')
    }
  }
}

필수적인 기본세팅은 이 설정이다. 추가적으로 더 설정할 수 있다.

이제 최종적으로 CORS문제 없이 도메인을 우회해서 api를 적용할 수 있다.