Node.js에서 Swagger를 활용하여 API 문서 자동화하기: 개발 생산성 향상을 위한 완벽 가이드

Node.js를 사용하여 RESTful API를 개발하는 과정에서 API 문서는 개발자 간의 효과적인 소통과 유지보수를 위한 필수적인 요소입니다. Swagger는 이러한 API 문서를 자동 생성하고 시각적으로 제공하여 개발 생산성을 향상시키는 강력한 도구입니다.

본 가이드에서는 Node.js 프로젝트에 Swagger를 도입하여 API 문서를 자동화하는 방법을 단계별로 설명하고, 다양한 활용 사례와 함께 깊이 있는 이해를 돕고자 합니다.

Swagger란 무엇인가?

Swagger는 RESTful API를 위한 인터페이스 명세 언어이자, 이를 기반으로 API 문서를 생성하고 시각화하는 도구입니다. Swagger를 사용하면 다음과 같은 이점을 얻을 수 있습니다.

• API 문서 자동 생성: 코드에 대한 주석만 추가하면 API 문서가 자동으로 생성됩니다.
• 시각적 API 문서: 직관적인 UI를 통해 API를 쉽게 탐색하고 테스트할 수 있습니다.
• 다양한 언어 및 프레임워크 지원: Node.js뿐만 아니라 다양한 언어와 프레임워크에서 사용할 수 있습니다.
• API 디자인 검증: API 설계 단계에서 오류를 미리 발견하고 수정할 수 있습니다.

Node.js 프로젝트에 Swagger 설정하기

1. 프로젝트 초기화:
   • Node.js 프로젝트를 생성하고 필요한 패키지를 설치합니다.
   • 일반적으로 Express 프레임워크를 사용하여 API 서버를 구축합니다.
   • Swagger를 위한 패키지 (예: swagger-jsdoc, swagger-ui-express)를 설치합니다.
2. Swagger 설정 파일 작성:
   • swagger.json 또는 swagger.yaml 파일을 생성하여 API 정보를 정의합니다.
   • API 경로, HTTP 메서드, 요청/응답 데이터 형식, 인증 방식 등을 상세하게 기술합니다.
3. Express 서버에 Swagger UI 연결:
   • swagger-ui-express 패키지를 사용하여 Swagger UI를 Express 서버에 연결합니다.
   • 특정 URL 경로로 접속하면 Swagger UI가 실행되어 API 문서를 확인할 수 있습니다.

728x90

Swagger 활용 예시

• API 문서 자동 생성:
  • 코드에 주석 형식으로 API 정보를 추가하면 Swagger가 자동으로 문서를 생성합니다.
  • 주석은 API 경로, HTTP 메서드, 요청/응답 데이터 형식, 설명 등을 포함합니다.
• API 시각화:
  • Swagger UI를 통해 API를 직관적으로 탐색하고 테스트할 수 있습니다.
  • API 엔드포인트, 요청 파라미터, 응답 예시 등을 한눈에 확인할 수 있습니다.
• API 디자인 검증:
  • Swagger 스펙에 맞게 API를 설계하면 일관성 있는 API를 구축할 수 있습니다.
  • API 디자인 오류를 사전에 발견하고 수정할 수 있습니다.
• 팀 협업:
  • Swagger 문서를 공유하여 개발팀 간의 효과적인 소통을 가능하게 합니다.
  • API 변경 사항을 실시간으로 반영하여 항상 최신 문서를 유지할 수 있습니다.

 

// 1. Node.js 프로젝트 생성
// package.json 파일 생성
{
  "name": "swagger-example",
  "version": "1.0.0",
  "description": "Node.js Swagger example",
  "main": "app.js",
  "scripts": {
    "start": "node app.js"
  },
  "dependencies": {
    "express": "^4.17.1",
    "swagger-ui-express": "^4.1.6",
    "swagger-jsdoc": "^6.1.0"
  }
}

// 2. Express.js 설치 (package.json에 이미 포함)

// 3. Swagger UI 및 Swagger-jsdoc 설치 (package.json에 이미 포함)

// 4. Swagger 설정 파일 작성 (app.js)
const express = require('express');
const swaggerJsdoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');

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

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'Node.js Swagger API',
      version: '1.0.0',
    },
  },
  apis: ['./routes/*.js'], // API 라우트 파일 위치
};

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

// 5. API 엔드포인트 생성 (routes/users.js)
const express = require('express');
const router = express.Router();

/**
 * @swagger
 * /users:
 *   get:
 *     summary: 모든 사용자 조회
 *     responses:
 *       200:
 *         description: 사용자 목록 반환
 */
router.get('/', (req, res) => {
  res.json([{ id: 1, name: 'John Doe' }, { id: 2, name: 'Jane Doe' }]);
});

/**
 * @swagger
 * /users/{id}:
 *   get:
 *     summary: 특정 사용자 조회
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: integer
 *     responses:
 *       200:
 *         description: 사용자 정보 반환
 *       404:
 *         description: 사용자를 찾을 수 없음
 */
router.get('/:id', (req, res) => {
  const userId = parseInt(req.params.id);
  if (userId === 1) {
    res.json({ id: 1, name: 'John Doe' });
  } else {
    res.status(404).json({ message: '사용자를 찾을 수 없습니다.' });
  }
});

module.exports = router;

// app.js (계속)
const usersRouter = require('./routes/users');
app.use('/users', usersRouter);

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

// 6. Swagger UI에서 API 문서 확인
// 브라우저에서 http://localhost:3000/api-docs 접속

이 코드는 Node.js 환경에서 Swagger를 사용하여 API 문서를 자동으로 생성하는 예제입니다. 먼저, Express.js를 설치하여 웹 서버를 구축하고, Swagger UI 및 Swagger-jsdoc을 통해 API 문서를 작성합니다. `app.js` 파일에서 Swagger 설정을 정의하고, `/api-docs` 경로를 통해 Swagger UI에 접근할 수 있도록 설정합니다. `routes/users.js` 파일에서는 사용자 정보를 반환하는 API 엔드포인트를 생성하고, Swagger 주석을 통해 API 문서화합니다.

개선점으로는, 현재 사용자 데이터가 하드코딩되어 있어 실제 데이터베이스와 연동할 수 있도록 수정하면 좋습니다. 또한, 에러 처리 및 입력 검증을 강화하여 API의 안정성을 높일 수 있습니다. 마지막으로, Swagger 문서에 더 많은 API 엔드포인트를 추가하여 전체적인 API 사용성을 향상시키는 것도 좋은 방향입니다.

 

심화 내용

• Swagger Customizations:
  • Swagger UI를 커스터마이징하여 프로젝트에 맞는 디자인을 적용할 수 있습니다.
  • 다양한 플러그인을 활용하여 기능을 확장할 수 있습니다.
• OpenAPI Specification:
  • Swagger는 OpenAPI Specification을 기반으로 합니다.
  • OpenAPI Specification을 깊이 이해하면 더욱 효과적으로 Swagger를 활용할 수 있습니다.
• Swagger와 CI/CD:
  • Swagger를 CI/CD 파이프라인에 통합하여 API 문서를 자동으로 생성하고 배포할 수 있습니다.

결론

Swagger는 Node.js 개발자에게 필수적인 도구입니다. Swagger를 활용하면 API 문서 작성에 드는 시간을 절약하고, API의 일관성과 유지보수성을 높일 수 있습니다. 본 가이드를 통해 Node.js 프로젝트에 Swagger를 도입하고, API 개발의 효율성을 높이시기 바랍니다.

  참고:

• Swagger 공식 문서: https://editor.swagger.io/
• Swagger-jsdoc: https://github.com/Surnet/swagger-jsdoc/blob/master/docs/FIRST-STEPS.md
• Swagger-ui-express: https://github.com/scottie1984/swagger-ui-express