Express는 Node.js를 위한 경량의 웹 애플리케이션 프레임워크로, RESTful API를 개발하는 데 매우 유용합니다. 이러한 API를 문서화하는 것은 개발자와 사용자, 그리고 팀 간의 소통을 원활하게 해주는 중요한 작업입니다. 이 글에서는 Express 서버를 구축하고, 자동으로 API 문서를 생성해주는 도구인 Swagger를 사용하여 문서화하는 방법을 설명하겠습니다.
1. Express 및 Swagger 소개
Express는 수많은 미들웨어와 함께 사용되어 뛰어난 유연성을 제공합니다. Swagger는 API 명세서를 자동으로 생성해주는 도구로, API 개발 과정에서의 문서화 및 테스트를 매우 간편하게 만들어줍니다.
1.1 Express란?
Express는 서버 사이드 애플리케이션 구축을 위한 간단한 API를 제공하는 웹 프레임워크입니다. 라우터, 미들웨어, HTTP 요청 및 응답 처리 기능이 포함되어 있어 RESTful API 개발에 특히 적합합니다.
1.2 Swagger란?
Swagger는 API를 정의하고 문서화하는 데 도움을 주는 도구입니다. Swagger의 주요 이점은 API 문서를 동적으로 생성하고, 사용자가 API를 테스트할 수 있는 UI를 제공한다는 점입니다.
2. 개발 환경 설정
이제 Express와 Swagger를 설정하는 방법에 대해 알아보겠습니다. 아래의 단계를 따라 해보세요.
2.1 Node.js 및 npm 설치
Node.js가 설치되어 있지 않은 경우 [Node.js 공식 웹사이트](https://nodejs.org/)에서 설치합니다. 설치가 완료되면, 다음 명령어로 Node.js와 npm이 정상적으로 설치되었는지 확인합니다:
node -v
npm -v2.2 프로젝트 폴더 생성 및 초기화
프로젝트를 진행할 폴더를 생성하고 npm을 사용하여 초기화합니다:
mkdir express-swagger-example
cd express-swagger-example
npm init -y2.3 Express 설치
다음 명령어로 Express를 설치합니다:
npm install express2.4 Swagger 관련 패키지 설치
Swagger UI와 Swagger-jsdoc을 설치합니다. Swagger UI는 API 문서를 시각화하여 보여주는 역할을 하고, Swagger-jsdoc은 JSDoc 스타일로 API 문서를 작성할 수 있게 해줍니다:
npm install swagger-ui-express swagger-jsdoc3. Express 애플리케이션 설정
이제 기본적인 Express 애플리케이션을 설정해 보겠습니다. index.js 파일을 생성하고 아래의 코드를 입력하세요:
const express = require('express');
const swaggerJsDoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');
const app = express();
const port = 3000;
// Swagger 설정
const swaggerOptions = {
swaggerDefinition: {
openapi: '3.0.0',
info: {
title: 'Express API Documentation',
version: '1.0.0',
description: '자동화된 문서화 API 예제',
},
servers: [
{
url: `http://localhost:${port}`,
},
],
},
apis: ['./routes/*.js'], // API 문서화할 경로
};
const swaggerDocs = swaggerJsDoc(swaggerOptions);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));
// 기본 라우트 예제
app.get('/', (req, res) => {
res.send('Hello World!');
});
// 서버 시작
app.listen(port, () => {
console.log(`Server is running on http://localhost:${port}`);
});3.1 Swagger 설정 설명
위 코드에서 swaggerDefinition 객체는 API 문서의 정보를 정의합니다. 여기에는 API의 이름, 버전, 설명 및 서버 정보를 설정합니다. apis 배열은 Swagger가 문서화할 API 파일의 경로를 지정합니다.
3.2 기본 라우트 추가
예제에서는 / 경로에 대한 GET 요청을 처리하는 기본 라우트를 추가했습니다. 이 라우트에 대한 Swagger 문서화도 추가해보겠습니다.
4. API 경로 문서화
다음으로, API 경로를 문서화할 파일인 routes/index.js 파일을 생성하고 아래의 코드를 입력해 보세요:
/**
* @swagger
* /:
* get:
* summary: Hello World를 응답합니다.
* responses:
* 200:
* description: 성공적으로 응답
*/
app.get('/', (req, res) => {
res.send('Hello World!');
});5. 서버 실행 및 Swagger UI 확인
모든 설정이 완료되었으면, 서버를 실행합니다:
node index.js브라우저에서 http://localhost:3000/api-docs를 열면 Swagger UI가 표시됩니다. 이 UI를 통해 API 문서와 함께 `Hello World!` 응답을 확인할 수 있습니다.
6. 다양한 API 문서화하기
위의 예제를 바탕으로, 보다 복잡한 API를 문서화할 수 있습니다. 예를 들어, 사용자의 CRUD(Create, Read, Update, Delete) 작업을 지원하는 API를 문서화해 보겠습니다.
6.1 CRUD API 설정
아래의 코드를 routes/user.js 파일에 추가합니다:
const express = require('express');
const router = express.Router();
/**
* @swagger
* /users:
* get:
* summary: 사용자 목록을 가져옵니다.
* responses:
* 200:
* description: 성공적으로 사용자 목록을 반환합니다.
*/
router.get('/', (req, res) => {
res.send('사용자 목록');
});
/**
* @swagger
* /users:
* post:
* summary: 새 사용자를 생성합니다.
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* properties:
* name:
* type: string
* age:
* type: integer
* responses:
* 201:
* description: 성공적으로 사용자 생성
*/
router.post('/', (req, res) => {
res.status(201).send('사용자 생성됨');
});
/**
* @swagger
* /users/{id}:
* get:
* summary: 특정 사용자의 정보를 가져옵니다.
* parameters:
* - in: path
* name: id
* required: true
* description: 사용자 ID
* schema:
* type: integer
* responses:
* 200:
* description: 사용자 정보 반환
*/
router.get('/:id', (req, res) => {
res.send(`사용자 ID: ${req.params.id}`);
});
/**
* @swagger
* /users/{id}:
* put:
* summary: 특정 사용자의 정보를 업데이트합니다.
* parameters:
* - in: path
* name: id
* required: true
* description: 사용자 ID
* schema:
* type: integer
* responses:
* 200:
* description: 사용자 정보 업데이트 성공
*/
router.put('/:id', (req, res) => {
res.send(`사용자 ID: ${req.params.id} 정보 업데이트됨`);
});
/**
* @swagger
* /users/{id}:
* delete:
* summary: 특정 사용자를 삭제합니다.
* parameters:
* - in: path
* name: id
* required: true
* description: 사용자 ID
* schema:
* type: integer
* responses:
* 204:
* description: 사용자 삭제 성공
*/
router.delete('/:id', (req, res) => {
res.status(204).send();
});
module.exports = router;6.2 라우터에 사용자 라우트 추가
위에서 생성한 사용자 라우트를 메인 애플리케이션에 추가해야 합니다. index.js 파일을 수정하고 사용자 라우터를 등록합니다:
const userRouter = require('./routes/user');
app.use('/users', userRouter);7. API 문서 확인
서버를 다시 실행한 다음, Swagger UI를 방문하여 /users에 대한 다양한 API에 대한 문서를 확인합니다. 이를 통해 사용자 목록 조회, 생성, 조회, 업데이트 및 삭제와 같은 기능을 확인할 수 있습니다.
8. 보안 및 기타 설정
생성한 API를 운영할 때는 보안 방법론 또한 고려해야 합니다. JWT(Json Web Token) 인증 방식을 통해 사용자를 인증하고 API에 접근할 수 있도록 설정할 수 있습니다. 또한, Express의 미들웨어를 통해 요청을 로깅하거나 에러 핸들링을 추가하는 것도 좋은 방법입니다.
9. 마무리
이번 글에서는 Express 서버를 설정하고 Swagger를 활용하여 자동으로 API 문서를 생성하는 방법에 대해 알아보았습니다. 문서화는 개발의 중요한 부분 중 하나이며, Swagger와 같은 도구를 활용하여 이를 쉽게 처리할 수 있습니다. 이러한 도구를 적극 활용하여 더 나은 API 개발 환경을 만들어 보시기 바랍니다.
추가적으로, Swagger를 사용하여 만들어진 UI는 API 소비자에게 유용한 정보를 제공하며, 테스트를 직접 해볼 수 있는 기능도 제공합니다. 또한, API 도메인에 포함된 모든 엔드포인트를 쉽게 탐색할 수 있습니다.
10. 참고 자료
지금까지 Express와 Swagger를 활용한 API 문서화에 대한 소개를 마칩니다. 질문이나 의견이 있으시면 언제든지 댓글로 남겨주세요!