타입스크립트와 OpenAPI로 타입 안정성 있는 API 구축하기

원문: 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를 만들 수 있습니다.

1. 타입스크립트 문서

2. OpenAPI 사양 문서