본문으로 건너뛰기

[실전 API 설계] - 13. Node.js와 스웨거 코드젠으로 백엔드 구축

13.2. 스웨거 코드젠 소개​

코드젠으로 클라이언트 코드 생성과 서버 코드 생성할 수 있다.

클라이언트 코드
코드젠을 통해 생성한 클라이언트 코드는 일종의 SDK로, 요청을 직접 생성해 API를 호출하지 않고 SDK를 사용해 애플리케이션을 만들 수 있음.

서버 코드
서버 코드는 서버 스텁 코드를 생성한다. 스텁 코드는 미완 코드로, 형태는 갖췄지만 기능을 제대로 수행할 수 없으므로 모의 데이터를 반환한다.

13.3. 백엔드 구조​

13.3.2. 백엔드 구조 분석​

코드젠이 생성한 nodejs-server 디렉터리 내용

  • .swagger-codegen: 코드젠 버전이 명시된 VERSION 파일이 있는 디렉터리
  • api: 입력으로 사용한 OpenAPI 파일을 수정한 내용을 담고 있는 openapi.yaml 파일이 있는 디렉터리
  • controllers: Default.js 파일이 있는 디렉터리. 이 파일에는 API 정의서에 명시된 경로 기준으로 명명된 함수 목록이 담겨 있음.
  • service: DefaultService.js 파일이 있는 디렉터리. 이 파일에는 controllers의 Default.js 파일 안에 있던 함수가 호출하는 서비스 함수가 들어 있음.
  • utils: API 응답을 만들어 내는 유틸 함수가 들어 있는 writer.js 파일이 있는 디렉터리.
  • index.js: 시작점으로, controllers 디렉터리와 api/openapi.yaml, oas3-tools 라이브러리 참조를 포함하고 있음
  • package.json

oas3-tools: OpenAPI를 읽어서 사용할 수 있는 유틸 함수를 포함하고 있는 라이브러리

자동 생성된 백엔드 코드는 컨트롤러와 서비스 구조를 갖고 있음.

  • index.js는 클라이언트 요청이 도달하면 요청을 컨트롤러에 디스패치 한다.
  • 모든 API 연산은, 서비스 함수를 호출해 요청을 처리하고 응답을 반환하는 컨트롤러 함수를 갖고 있다. 컨트롤러 함수는 controllers 디렉터리에 정의.
  • 컨트롤러가 호출하는 서비스 함수는 요청을 처리한다. 서비스 함수는 service 디렉터리 안에 정의.

13.3.3. OpenAPI 수정 내용​

openapi.yaml의 첫 번째 경로에 2개의 새로운 키워드가 있음.

  • operationId: 연산마다 지정되어 있다. 코드젠이 경로와 메서드를 합쳐서 만들어 낸 값. (/users 경로의 POST 메서드면 usersPOST)
  • x-swagger-router-controller: Default로 지정되어 있음. Default는 컨트롤러에 있던 파일 이름.

지정된 경로로 요청이 들어오면 x-swagger-router-controller로 지정된 컨트롤러 파일에서 operationId로 지정된 함수에 요청을 전달함.

13.4. 백엔드 OpenAPI 수정​

13.4.1. operation ID 추가​

코드젠은 operation ID를 함수 이름으로 사용하며, 유일한 식별자로 사용됨.

정의한 operation ID를 OpenAPI 정의서의 각 연산에 추가함.

openapi: 3.0.3
#...
paths:
/users:
post:
summary: Register User
operationId: registerUser // 추가
responses:
'201':
...
#...

13.4.2. API 연산에 태그 지정​

따로 지정하지 않으면 코드젠은 모든 컨트롤러 함수를 Default 파일에 몰아넣는다. 이때, 태그로 여러 개의 연산들을 분리하고 그룹 지어 표시할 수 있음.

태그를 정의하고 OpenAPI 파일에 예제를 추가한다.

openapi: 3.0.3
info:
title: Open API
version: "0.1"
tags:
- name: Users
description: User-related operations
- name: Jobs
description: Job-related operations

이후, 연산에도 태그를 지정한다.

openapi: 3.0.3
#...
paths:
/users:
post:
tags:
- Users // 추가
summary: Register User
operationId: registerUser
responses:
'201':
...
#...

13.4.3. 백엔드 스텁 재생성​

operationId와 태그를 추가한 후, 백엔드 스텁 코드를 다시 생성한다.

이전과 비교해 다음과 같은 차이가 있다.

  • controllers 디렉터리에 Default.js 대신 태그를 따라 Users.js와 Jobs.js 파일이 생성됨.
  • service 디렉터리에도UsersService.js와 JobsService.js 파일이 생성됨.
  • 컨트롤러와 서비스 안에 있는 함수는 태그에 따라 분리된 파일 안에 정의됨.