API 스펙 자동화(OpenAPI/Swagger)와 Node.js 연동

소개

API 스펙 자동화는 개발 속도를 높이고 클라이언트와의 소통을 명확하게 만든다. Node.js 기반 서버에 OpenAPI(구 Swagger)를 통합하면 코드와 스펙을 일관되게 유지할 수 있다. 이 글은 처음 접하는 개발자도 이해하기 쉽도록 실무에서 자주 쓰이는 도구와 설정 흐름을 정리한다.

핵심 개념

OpenAPI와 Swagger의 차이

OpenAPI는 API 규격 표준이다. Swagger는 그 규격을 이용해 문서화와 UI를 제공하는 도구 모음이다. 흔히 Swagger UI와 swagger-jsdoc 같은 라이브러리를 함께 사용해 자동화된 스펙을 생성하고 브라우저에서 확인한다.

왜 자동화가 필요한가

• 스펙과 코드 불일치로 인한 버그 감소
• 클라이언트와 서버 간 계약을 명확히 유지
• 테스트와 배포 파이프라인에 통합 가능

필수 도구

• express: 서버 프레임워크
• swagger-jsdoc: JSDoc 주석으로부터 OpenAPI 스펙 생성
• swagger-ui-express: 생성된 스펙을 브라우저에서 제공

설치

프로젝트 디렉터리에서 필요한 패키지를 설치한다. 예제는 npm 기준이다.

npm install express swagger-jsdoc swagger-ui-express

구현 흐름

핵심 단계는 다음과 같다.

• swagger-jsdoc 설정으로 OpenAPI 정의 구성
• JSDoc 주석으로 각 라우트에 스펙 추가
• swagger-ui-express로 /api-docs 같은 경로에 UI 제공

예제 코드

아래는 최소한의 Express 연동 예제다. 실제 프로젝트에서는 routes 폴더를 분리해 관리한다.

const express = require('express');
const swaggerJsdoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');

const app = express();

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'Example API',
      version: '1.0.0',
      description: 'Sample API for demo'
    }
  },
  apis: ['./routes/*.js', './server.js']
};

const specs = swaggerJsdoc(options);

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));

app.get('/health', (req, res) => {
  res.json({ status: 'ok' });
});

app.listen(3000, () => console.log('Server started on 3000'));

라우트에 스펙 주석 추가

swagger-jsdoc는 JSDoc 스타일 주석을 읽어 OpenAPI 스펙으로 변환한다. 예시는 routes/users.js 파일의 주석이다.

/**
 * @openapi
 * /users:
 *   get:
 *     summary: 사용자 목록 조회
 *     responses:
 *       '200':
 *         description: 성공
 */
app.get('/users', (req, res) => {
  res.json([{ id: 1, name: '홍길동' }]);
});

Swagger UI 커스터마이징

swagger-ui-express는 기본 설정 외에 테마나 문서 기본값을 바꿀 수 있다. setup 함수에 추가 옵션을 전달해 로고나 기능을 조정할 수 있다. 또한 생산 환경에서는 인증이 필요한 엔드포인트로 UI 접근을 제한하는 것이 일반적이다.

CI/CD와 통합

스펙을 자동 생성하면 배포 파이프라인에서 스펙 유효성 검사, 변경 로그 생성, 클라이언트 SDK 자동 생성 같은 작업을 추가할 수 있다. 예를 들어 테스트 단계에서 swagger-cli 같은 도구로 OpenAPI 파일 유효성을 검사하면 스펙 오류를 조기에 발견할 수 있다.

권장 구조

• routes/ : 라우트 파일과 JSDoc 주석 분리
• docs/ : 빌드된 OpenAPI JSON 보관(선택사항)
• config/swagger.js : swagger-jsdoc 옵션 중앙화

자주 발생하는 문제와 해결

apis 경로가 잘못된 경우

swagger-jsdoc의 apis 배열에 지정한 경로가 실제 파일 위치와 일치하는지 확인한다. 상대 경로 오류가 가장 흔하다.

스펙이 누락되는 경우

JSDoc 주석 형식이 OpenAPI 규격과 맞지 않으면 누락이 발생한다. 들여쓰기와 키 이름을 정확히 맞춰야 한다.

마무리

Node Swagger 설정 Node.js 환경에서 OpenAPI 자동 문서화 Node 흐름을 이해하면 팀 협업과 유지보수가 쉬워진다. Swagger UI Express 설정으로 시각화하면 API 소비자가 빠르게 파악할 수 있다. 처음에는 설정이 번거롭게 느껴질 수 있지만, 일단 적용하면 반복 작업을 줄이고 신뢰도를 높일 수 있다.