웹 애플리케이션에서 API는 중요한 역할을 합니다. 특히, 백엔드 개발에서는 API를 통해 클라이언트와 서버 간의 통신을 원활하게 이루어질 수 있게 합니다. 따라서, API 문서화는 팀원 간의 이해를 높이고, 유지 보수를 용이하게 하는 중요한 작업입니다. 오늘은 Express.js 백엔드 서버를 개발하며 Swagger와 Postman을 이용해 API 문서화하는 방법에 대해 알아보겠습니다.
1. Express.js 소개
Express.js는 Node.js를 위한 최소화된 웹 프레임워크로, 웹 애플리케이션과 APIs를 개발하는 데 사용됩니다. Express는 다양한 미들웨어와 라우팅 기능을 제공하여 개발자가 효율적으로 웹 애플리케이션을 구축할 수 있도록 도와줍니다.
2. Express 프로젝트 설정
bash
# Express 프로젝트 생성
mkdir express-api-demo
cd express-api-demo
npm init -y
npm install express
위 명령어를 사용하여 Express 프로젝트를 생성하고, Express.js 패키지를 설치합니다.
2.1 기본 서버 설정
javascript
const express = require('express');
const app = express();
const PORT = 3000;
app.get('/', (req, res) => {
res.send('Hello, Express!');
});
app.listen(PORT, () => {
console.log(`Server is running on http://localhost:${PORT}`);
});
이제 기본 Express 서버가 설정되었습니다. npm start로 서버를 실행하면 http://localhost:3000에서 “Hello, Express!” 메시지를 볼 수 있습니다.
3. Swagger를 이용한 API 문서화
Swagger는 RESTful API의 설계, 문서화 및 테스트를 위한 통합 솔루션입니다. Swagger UI는 API를 시각적으로 표현하여 개발자와 비개발자가 쉽게 이해할 수 있도록 도와줍니다. 이제 Swagger를 Express 프로젝트에 통합하는 방법을 살펴보겠습니다.
3.1 Swagger UI와 Swagger JSDoc 설치
bash
npm install swagger-ui-express swagger-jsdoc
3.2 Swagger 설정
Swagger를 설정하기 위해 아래와 같이 코드를 수정합니다.
javascript
const swaggerJsDoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');
const swaggerOptions = {
swaggerDefinition: {
openapi: '3.0.0',
info: {
title: 'Express API Demo',
version: '1.0.0',
description: 'API documentation for Express Demo',
},
servers: [
{
url: 'http://localhost:3000',
},
],
},
apis: ['./routes/*.js'], // API 문서화할 파일 경로
};
const swaggerDocs = swaggerJsDoc(swaggerOptions);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));
3.3 API 문서화 주석 추가
Swagger에서 API를 문서화하기 위해 각 API 함수 위에 JSDoc 주석을 추가해야 합니다. 다음은 간단한 GET API에 대한 예입니다.
javascript
/**
* @swagger
* /:
* get:
* summary: Returns a Hello message
* responses:
* 200:
* description: A Hello message
*/
app.get('/', (req, res) => {
res.send('Hello, Express!');
});
이제 서버를 다시 실행하고 http://localhost:3000/api-docs로 이동하면 Swagger UI를 통해 API 문서를 확인할 수 있습니다.
4. Postman을 이용한 API 테스트 및 문서화
Postman은 API를 테스트하고 문서화하는 데 널리 사용되는 도구입니다. Postman을 사용하여 API를 쉽게 테스트하고, 테스트 결과를 문서화하는 방법을 알아보겠습니다.
4.1 Postman 설치
Postman은 공식 웹사이트에서 다운받아 설치할 수 있습니다. 설치 후 애플리케이션을 열고 API 요청을 생성할 수 있습니다.
4.2 API 요청 만들기
Postman에서 새 요청을 만들고, HTTP 메서드와 URL을 입력하여 API 요청을 구성합니다. 아래는 GET 요청의 예입니다.
plaintext
Method: GET
URL: http://localhost:3000/
4.3 요청 테스트 및 응답 확인
위와 같이 요청을 구성한 후, Send 버튼을 클릭하여 요청을 전송합니다. 올바르다면 “Hello, Express!”라는 응답을 확인할 수 있습니다.
4.4 API 문서화
Postman은 요청이 성공적으로 완료된 후, 요청 정보를 문서화할 수 있는 기능을 제공합니다. 요청을 선택한 뒤 우측 상단의 ... 메뉴에서 Save as Template을 선택하여 요청 정보를 저장할 수 있습니다.
5. API 문서화의 중요성
API 문서화는 개발자의 생산성을 높이고, 유지 보수를 용이하게 만들며, 팀과의 협업을 촉진합니다. Swagger와 Postman은 이러한 문서화 과정을 간소화해주며, 팀원들이 API의 작동 방식을 쉽게 이해할 수 있도록 도와줍니다.
6. 결론
오늘 우리는 Express.js를 사용한 간단한 API 서버를 설정하고, Swagger와 Postman을 통해 API를 문서화하는 방법을 알아보았습니다. 이 과정에서 얻은 지식을 바탕으로, 앞으로 더욱 효율적으로 API를 개발하고 문서화할 수 있기를 바랍니다.