TypeScript의 필요성
TypeScript는 JavaScript의 슈퍼셋으로, 정적 타입을 지원하여 코드의 안정성과 유지보수성을 향상시킵니다. JavaScript는 동적 타입 언어로, 런타임에 타입 오류가 발견될 수 있습니다. TypeScript는 컴파일 타임에 타입 오류를 잡아줌으로써 이러한 문제를 방지합니다.
1️⃣ 정적 타입 검사
TypeScript는 변수, 함수 인자, 반환 값 등에 타입을 명시적으로 정의할 수 있습니다. 이는 코드를 작성하는 도중에 타입 오류를 사전에 방지할 수 있게 합니다.
2️⃣ 코드 가독성 및 유지보수성 향상
명시적인 타입 선언은 코드의 의도를 명확히 하여 다른 개발자가 코드를 이해하고 유지보수하는 데 큰 도움을 줍니다. 이는 팀 프로젝트에서 특히 유용합니다.
3️⃣ 개발자 도구 지원 강화
TypeScript는 다양한 IDE와의 호환성이 좋아 코드 자동 완성, 디버깅 등의 도구를 효과적으로 활용할 수 있습니다.
요즘 프론트엔드 개발에서 TypeScript는 선택이 아닌 필수입니다.
TypeScript의 문제점
하지만 TypeScript의 단점도 존재하는데요,
귀찮다는 것입니다.
API 통신을 하는 경우를 생각해보겠습니다.
모든 API에 대해서 요청, 응답, 에러 응답 각각에 해당하는 타입 정의가 필요합니다.
POST 요청들의 경우 응답 DTO나 에러 DTO는 재사용할 수 있겠지만
요청 DTO는 모두 다르게 생겼을 것이며, GET요청의 경우에는 각 응답에 대한 타입 정의가 필요할 것입니다.
이렇듯 API 통신에 필요한 모든 DTO에 대한 타입을 직접 정의하고 작성하는 것은 쉬운일이 아닙니다.
라이브러리 소개 - OpenAPI TypeScript
OpenAPI Specification(OAS)을 기반으로 TypeScript 타입을 생성하는 도구입니다. 이는 API 타입 정의를 자동화하여 개발 생산성을 높이고, 타입 안전성을 보장합니다.
주요 기능
- 자동 타입 생성: OAS에서 TypeScript 타입을 자동으로 생성합니다.
- 타입 안전성: 생성된 타입을 사용하여 API 호출 시 타입 오류를 사전에 방지할 수 있습니다.
- 유지보수성 향상: API 변경 시, 라이브러리를 그저 재실행 시키는 것으로 타입을 업데이트하여 유지보수를 간소화합니다.
OpenAPI Specification(OAS)란?
OpenAPI Specification(OAS)는 RESTful API를 설계하고 문서화하기 위한 표준 포맷입니다.
API의 엔드포인트, 요청/응답 구조, 인증 방식 등을 JSON 또는 YAML 형식으로 정의하며, API의 동작을 명확히 기술해 개발, 테스트, 문서화를 효율적으로 지원합니다.
쉽게 말해, API 사용 설명서(명세서)를 코드로 작성한 것이라 생각하면 됩니다.
또한 Swagger는 이를 작성, 문서화, 테스트, 시뮬레이션하는 데 도움을 주는 도구라고 할 수 있습니다.
사용방법
OAS 파일의 위치와, 실행 결과(생성된 타입들)가 저장될 위치를 지정해주고 npx 명령어를 통해 실행시켜 주면 됩니다. 간단하죠?
package.json에 scripts를 추가해놓으면 더 편하게 사용하실 수 있습니다!
Swagger에서 OAS파일은 어디에 있나요?
Swagger URL이
https://api.example-url.com이라면, 다음 경로에서 OpenAPI Specification(OAS) 파일을 찾을 수 있습니다.
1. 뒤에/v2/api-docs또는/v3/api-docs이 붙는 경우https://api.example-url.com/v2/api-docs // Swagger 2.0 기본 경로 https://api.example-url.com/v3/api-docs // OpenAPI 3.0 기본 경로2. 뒤에
/swagger.json또는/swagger.yaml이 붙는 경우https://api.example-url.com/swagger.json // json 파일 https://api.example-url.com/swagger.yaml // yaml 파일서버 설정에 따라 경로가 다를 수 있습니다.
브라우저 개발자 도구(F12) → Network 탭에서 Swagger UI가 호출하는 JSON/YAML 파일 경로를 확인할 수 있습니다.
추가 설정
// tsconfig.json
{
"compilerOptions": {
"module": "ESNext", // 최신 ES 모듈(import/export) 문법을 사용하기 위해 설정
"moduleResolution": "Bundler", // 번들러(Webpack, Vite 등)와 호환되는 모듈 해석 방식 사용
"noUncheckedIndexedAccess": true // 객체 인덱싱 시 undefined 가능성을 강제 검토하여 타입 안전성 강화
}
}OpenAPI TypeScript 코드가 프로젝트와 완벽히 호환되도록 하기 위해,
공식문서에서는 위와 같은 설정을 추가할 것을 권장하고 있습니다.
타입 사용
npx 명령어가 정상적으로 실행되었다면, 사진과 같은 구조의 파일이 생긴 것을 확인하실 수 있습니다.
API 통신에서 사용하는 스키마들은 components 부분에 정의되어있습니다.
실제로 위 사진과 같이, components 안에 schemas 안에 실제 DTO들이 정의되어 있는 것을 볼 수 있습니다.
그러므로 특정 타입을 사용하고 싶다면
import { components } from "@schema";
// 스키마 객체 타입
type MyResponseType = components['schemas']['MyResponseType'];이와 같이 해당 파일에서 components import 하고, components['schemas']['이름']으로 타입을 사용할 수 있습니다.
한 걸음 더
OpenAPI fetch를 활용하면 API 명세에 따라 효율적이고 타입 안전한 API 호출을 구현할 수 있습니다.
참고자료
