📃 Swagger로 REST API 문서 자동화하기

📌 개요

백엔드 API를 만들었지만, 문서화는 매번 귀찮고 누락되기 쉽습니다.
이럴 때 사용하면 좋은 도구가 바로 **Swagger (OpenAPI)**입니다.
이번 글에서는 Node.js + Express 환경에서 Swagger를 설치하고,
자동으로 API 문서를 생성하고 테스트하는 방법을 알려드릴게요.

---

🧠 핵심 개념

🔍 Swagger란?

• REST API를 시각적으로 문서화하고 테스트할 수 있는 도구
• OpenAPI 스펙을 기반으로 자동 문서 생성
• API 스펙 공유, 테스트, 버전 관리까지 용이

📘 Swagger의 주요 도구

• swagger-jsdoc: 주석 기반으로 Swagger 스펙 자동 생성
• swagger-ui-express: 생성된 스펙을 웹 페이지 형태로 표시

---

💡 실전 팁 또는 실습

🛠️ 1단계: 패키지 설치

npm install swagger-jsdoc swagger-ui-express

---

📁 2단계: Swagger 설정 추가

// swagger.js
const swaggerJsdoc = require("swagger-jsdoc");
const swaggerUi = require("swagger-ui-express");

const options = {
  swaggerDefinition: {
    openapi: "3.0.0",
    info: {
      title: "My REST API",
      version: "1.0.0",
      description: "나만의 Express 기반 API 문서입니다."
    },
    servers: [{ url: "http://localhost:3000" }]
  },
  apis: ["./index.js"] // 주석 기반 API 정의가 포함된 파일 경로
};

const specs = swaggerJsdoc(options);

module.exports = { swaggerUi, specs };

---

🧾 3단계: Express에 Swagger 적용

 

// index.js
const express = require('express');
const app = express();
const PORT = 3000;

const { swaggerUi, specs } = require('./swagger');

app.use(express.json());
app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(specs));

app.listen(PORT, () => {
  console.log(`서버 실행 중: http://localhost:${PORT}`);
  console.log(`Swagger 문서: http://localhost:${PORT}/api-docs`);
});

---

✍️ 4단계: 주석으로 API 문서화

/**
 * @swagger
 * /hello:
 *   get:
 *     summary: Hello API
 *     description: 간단한 테스트용 API
 *     responses:
 *       200:
 *         description: 성공 응답
 */
app.get("/hello", (req, res) => {
  res.send("Hello Swagger!");
});

---

✅ 마무리

Swagger는 단순한 문서 도구가 아니라 개발자와의 소통 툴입니다.
주석만 잘 달아도 자동으로 API 문서가 만들어지고, 클라이언트도 직접 테스트할 수 있어요.

실무에선 Swagger를 쓰는 것만으로도 협업 효율, 유지보수성, 신뢰도가 모두 올라갑니다.

---

📎 다음 글 예고

• 딥러닝 OCR: EasyOCR vs PaddleOCR 비교
• Swagger 문서를 GitHub Pages에 배포하기
• Swagger + JWT 인증 연동 방법