원문: Alexander Obregon, "Building Type-safe APIs with TypeScript and OpenAPI"
소개
최신 웹 개발에서 타입 안정성은 안정적이고 유지 관리가 가능한 애플리케이션을 구축하는 데 중요한 역할을 합니다. 정적 타입을 지원하는 자바스크립트의 상위 집합인 타입스크립트는 타입 안정성을 중시하는 개발자가 선호하는 언어가 되었습니다. 반면 OpenAPI는 API를 설계, 구축, 문서화 및 테스트하는 데 도움이 되는 보편적인 API 설명 형식입니다.
이 글에서는 타입스크립트 및 OpenAPI를 사용하여 타입 안정성 있는 API를 만드는 방법을 살펴보겠습니다. 기사 모음을 관리하기 위한 간단한 REST API 구축 과정을 통해 이를 설명하겠습니다.
1단계: 프로젝트 설정하기
시작하려면 프로젝트에 대한 새 폴더를 만들고 npm으로 초기화하세요.
mkdir type-safe-api
cd type-safe-api
npm init -y
다음으로 필요한 종속성을 설치합니다.
npm install --save express
npm install --save-dev typescript @types/express ts-node
프로젝트 루트에 tsconfig.json
파일을 만듭니다.
{
"compilerOptions": {
"target": "es6",
"module": "commonjs",
"outDir": "./dist",
"strict": true,
"esModuleInterop": true
},
"include": ["src/**/*.ts"],
"exclude": ["node_modules"]
}
2단계: OpenAPI 사양 정의하기
openapi
라는 새 폴더를 만들고 그 안에 spec.yml
파일을 만듭니다. OpenAPI 사양을 사용해 API를 정의합니다.
openapi: 3.0.0
info:
title: Article API
version: 1.0.0
paths:
/articles:
get:
summary: Get all articles
responses:
'200':
description: A list of articles
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Article'
components:
schemas:
Article:
type: object
properties:
id:
type: string
title:
type: string
content:
type: string
required:
- id
- title
- content
3단계: OpenAPI 사양에서 타입스크립트 타입 생성하기
OpenAPI 사양에서 타입스크립트 타입을 생성하려면 openapi-typescript
패키지를 설치합니다.
npm install --save-dev openapi-typescript
타입을 생성하려면 package.json
에 스크립트를 추가하세요.
"scripts": {
"generate-types": "openapi-typescript openapi/spec.yml --output src/types/api.ts"
}
스크립트를 실행해 타입을 생성합니다.
npm run generate-types
4단계: 타입 안정성을 갖춘 API 구현하기
src
라는 새 폴더를 만들고 그 안에 index.ts
파일을 만듭니다. 필요한 모듈과 생성된 타입을 가져옵니다.
import express from "express";
import { Article } from "./types/api";
기사를 저장하기 위한 용도로 간단한 메모리 내 저장소를 만듭니다.
const articles: Article[] = [];
모든 기사를 가져오는 경로를 정의합니다.
const app = express();
app.use(express.json());
app.get("/articles", (req, res) => {
res.json(articles);
});
마지막으로 서버를 시작합니다.
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
console.log(`Server is running on port ${PORT}`);
});
이제 타입스크립트 및 OpenAPI를 사용하여 타입 안정성 있는 API를 갖게 되었습니다. API가 성장함에 따라 더 많은 엔드포인트를 쉽게 추가하여 모든 단계에서 타입 안정성을 보장할 수 있습니다.
5단계: OpenAPI 사양 업데이트하기
spec.yml
에서 /articles
경로에 post
엔드포인트를 추가합니다.
post:
summary: Create a new article
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ArticleInput'
responses:
'201':
description: The created article
content:
application/json:
schema:
$ref: '#/components/schemas/Article'
그리고 components
섹션에서 ArticleInput
스키마를 정의합니다.
ArticleInput:
type: object
properties:
title:
type: string
content:
type: string
required:
- title
- content
6단계: 타입스크립트 타입 재생성하기
업데이트된 OpenAPI 사양을 기반으로 타입스크립트 타입을 다시 생성하려면 스크립트를 실행하세요.
npm run generate-types
7단계: 기사 생성 엔드포인트 구현하기
새로운 ArticleInput
타입을 포함하도록 index.ts
파일을 업데이트하고 기사 생성 엔드포인트를 구현합니다.
import { v4 as uuidv4 } from "uuid";
import { Article, ArticleInput } from "./types/api";
// ...
app.post("/articles", (req, res) => {
const articleInput: ArticleInput = req.body;
const newArticle: Article = { ...articleInput, id: uuidv4() };
articles.push(newArticle);
res.status(201).json(newArticle);
});=
이제 API에는 기사 관리를 위한 get
과 post
의 두 가지 엔드포인트와 타입스크립트 및 OpenAPI를 사용하여 모두 타입 안정성이 구현되었습니다. API를 계속 개발하면서 타입 안정성 기능을 활용하여 잠재적인 오류를 조기에 포착하고 개발 프로세스를 간소화하며 전반적인 코드 품질을 향상할 수 있습니다.
결론
타입스크립트와 OpenAPI는 함께 타입 안정성 있는 API를 구축하기 위한 강력한 조합을 제공합니다. 이러한 도구를 활용하면 향상된 개발자 경험과 코드 품질을 갖춘 강력하고 유지 관리 가능한 API를 만들 수 있습니다.