Node.js 프로젝트에서 OpenAPI Generator로 API 코드 자동화하기

OpenAPI Generator란?

OpenAPI Generator는 OpenAPI (Swagger) 스펙을 기반으로 다양한 언어와 프레임워크에 대한 클라이언트 및 서버 코드를 자동으로 생성해주는 도구입니다. 이를 통해 API 개발 및 문서화 과정을 효율적으로 관리할 수 있습니다.

1. OpenAPI Generator 설치

먼저, OpenAPI Generator를 설치합니다. Node.js 환경에서 `npm` 또는 `yarn`을 사용하여 설치할 수 있습니다.

npm install @openapitools/openapi-generator-cli -g

or

yarn global add @openapitools/openapi-generator-cli

2. OpenAPI 스펙 파일 준비

API 문서화를 위해 OpenAPI 스펙 파일 (`openapi.yaml` 또는 `openapi.json`)을 준비합니다. 이 파일에는 API의 엔드포인트, 요청 및 응답 형식, 모델 등이 정의되어 있어야 합니다.

`openapi.yaml` 파일 예시

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Get all users
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

3. `openapi.json` 파일 설정

프로젝트 루트 디렉토리에 `openapi.json` 파일을 생성합니다. 이 파일은 OpenAPI Generator가 생성할 코드의 구조를 정의합니다.

{
	"modelPackage": "src/model",
	"apiPackage": "api",
	"withSeparateModelAndApi": true
}

• modelPackage: API 모델 정의 파일이 위치할 디렉토리
• apiPackage: API 엔드포인트 핸들러 파일이 위치할 디렉토리
• withSeparateModelAndApi: 모델과 API 코드를 분리하여 생성

4. `openapitools.json` 파일 설정

OpenAPI Generator CLI의 설정을 위한 `openapitools.json` 파일도 필요합니다.

{
	"$schema": "./node_modules/@openapitools/openapi-generator-cli/config.schema.json",
	"spaces": 2,
	"generator-cli": {
		"version": "6.2.0"
	},
	"enumPropertyNaming": "original"
}

• $schema:@b] JSON 스키마 파일의 경로
• spaces:@b] 들여쓰기 공백 수
• generator-cli:@b] 사용할 OpenAPI Generator CLI 버전
• enumPropertyNaming:@b] 열거형 속성의 네이밍 규칙

5. 코드 생성

OpenAPI Generator를 사용하여 코드를 생성합니다.

openapi-generator-cli generate -i openapi.yaml -g nodejs-express-server -o ./generated --config openapi.json

• -i: 입력 파일 경로 (OpenAPI 스펙 파일)
• -g: 코드 생성기 유형 (`nodejs-express-server`)
• -o: 출력 디렉토리
• –config: 추가 설정 파일 (`openapi.json`)

6. 생성된 코드 사용

생성된 코드는 `./generated` 디렉토리에 위치하게 됩니다. 이 코드를 프로젝트에 통합하여 사용할 수 있습니다.

Express 서버 실행 예시:

const express = require('express');
const app = express();
const port = 3000;

// Include generated API routes
const apiRoutes = require('./generated/api');

app.use('/api', apiRoutes);

app.listen(port, () => {
  console.log(`Server is running on http://localhost:${port}`);
});

결론

OpenAPI Generator를 사용하면 API 개발 및 문서화 과정을 효율적으로 관리할 수 있습니다. `openapi.json` 및 `openapitools.json` 파일을 적절히 설정하여 프로젝트에 맞게 자동화된 코드 생성을 수행해보세요. 이를 통해 개발 시간을 절약하고, 코드의 일관성과 유지 보수성을 높일 수 있습니다.

Node.js 프로젝트에서 OpenAPI Generator를 활용하는 방법을 이해하고 적용하면, API 개발 및 관리의 효율성을 크게 향상시킬 수 있습니다. 이 가이드를 따라 OpenAPI Generator를 설치하고 설정하여 API 코드 자동화를 시작해보세요.