라우트, Swagger

1. 라우트(Route)

웹 애플리케이션에서 클라이언트가 요청한 URL 경로와 HTTP 메서드(GET, POST 등)에 따라 서버가 어떤 동작을 수행할지를 정의한다.

라우팅은 웹 서버가 어떤 페이지나 데이터를 제공할지를 결정하는 핵심적인 구조이다.

1. route 메서드

Express의 .route() 메서드는 동일한 URL 경로에 대해 여러 HTTP 메서드(GET, POST, PUT 등)를 체이닝 방식으로 한 번에 정의할 수 있게 해주는 기능이다.

.route() 메서드를 사용하면 코드가 더 간결하고 구조화되어 유지보수에 유리하다.

✨ 14_route.mjs

import express from "express";

const app = express();

app
  .route("/posts")
  .get((req, res) => {
    res.status(200).send("/posts GET 호출!");
  })
  .post((req, res) => {
    res.status(201).send("/posts POST 호출!");
  })
  .put((req, res) => {
    res.status(201).send("/posts PUT 호출!");
  })
  .delete((req, res) => {
    res.status(204).send("/posts DELETE 호출!");
  });

app.listen(3000, () => {
  console.log("서버 실행 중");
});

상태 코드	이름	의미	응답 본문	주요 사용 상황
200	OK	요청이 성공적으로 처리되었고, 응답 데이터도 함께 반환됨	✅ 있음	GET 요청, 일반적인 요청 응답
201	Created	새로운 리소스가 성공적으로 생성되었음	✅ 있음	POST 요청 (리소스 생성)
204	No Content	요청은 성공했지만, 클라이언트에 보낼 데이터는 없음	❌ 없음	DELETE, PUT 등 (본문 없음 응답)

/posts delete 호출 시, 이렇게 204 옆에 No Content 라고 뜬다.

❇️ 15_routing.mjs

import express from "express";
import userRouter from "./routes/user.mjs";
import postRouter from "./routes/post.mjs";

const app = express();
app.use(express.json());

// http://127.0.0.1:3000/users
app.use("/users", userRouter);

// http://127.0.0.1:3000/posts
app.use("/posts", postRouter);

app.listen(3000, () => {
  console.log("서버 실행 중");
});

❇️ /routes/user.mjs

import express from "express";

const router = express.Router();

router.use((req, res, next) => {
  console.log("users에 존재하는 미들웨어");
  next();
});

// http://127.0.0.1:3000/users
router.get("/", (req, res) => {
  res.status(200).send("GET: /users 회원정보보기");
});

router.post("/", (req, res) => {
  res.status(201).send("POST: /users 회원가입");
});

router.put("/:id", (req, res) => {
  res.status(201).send("PUT: /users/:id 정보수정");
});

router.delete("/:id", (req, res) => {
  res.status(201).send("DELETE: /users/:id 회원탈퇴");
});

export default router;

❇️ /routes/post.mjs

import express from "express";

const router = express.Router();

router.use((req, res, next) => {
  console.log("posts에 존재하는 미들웨어");
  next();
});

// http://127.0.0.1:3000/posts
router.get("/", (req, res) => {
  res.status(200).send("GET: /posts 글 보기");
});

router.post("/", (req, res) => {
  res.status(201).send("POST: /posts 글 작성하기");
});

router.put("/:id", (req, res) => {
  res.status(201).send("PUT: /posts/:id 글 수정하기");
});

router.delete("/:id", (req, res) => {
  res.status(200).send("DELETE: /posts/:id 글 삭제하기");
});

export default router;

2. Swagger

RESTful API를 문서화하고 시각적으로 테스트할 수 있도록 도와주는 오픈소스 도구 모음이다. Swagger

개발자가 API의 구조와 사용 방법을 명확히 정의할 수 있도록 해주며,
작성한 API 문서를 웹 브라우저에서 Swagger UI를 통해 쉽게 확인하고 직접 테스트할 수 있다.

✨ 16_swagger.js

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

const swaggerUi = require("swagger-ui-express");
const swaggerSpec = require("./swagger");
const postRoutes = require("./routes/posts");

app.use(express.json());

// Swagger UI 라우트 등록
app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(swaggerSpec));

// 실제 API 라우트
app.use("/posts", postRoutes);

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

✨ /routes/posts.js

const express = require("express");
const router = express.Router();

/**
 * @swagger
 * /posts:
 *   get:
 *     summary: 모든 게시글 조회
 *     responses:
 *       200:
 *         description: 게시글 목록 성공 응답
 *   post:
 *     summary: 새 게시글 생성
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             properties:
 *               title:
 *                 type: string
 *               content:
 *                 type: string
 *     responses:
 *       201:
 *         description: 생성 성공
 */
router.get("/", (req, res) => {
  res.send("모든 게시글 조회");
});

router.post("/", (req, res) => {
  res.status(201).send("게시글이 생성되었습니다");
});

module.exports = router;

✨ swagger.js

const swaggerJSDoc = require("swagger-jsdoc");

const options = {
  definition: {
    openapi: "3.0.0",
    info: {
      title: "게시판 API",
      version: "1.0.0",
      description: "게시글 관련 REST API 문서입니다.",
    },
    servers: [
      {
        url: "http://localhost:3000",
      },
    ],
  },
  apis: ["./routes/*.js"], // 주석으로부터 API 문서 생성
};

const swaggerSpec = swaggerJSDoc(options);
module.exports = swaggerSpec;

이렇게 실행 후에,
여기서 Swagger 문서 보기 : 링크 (← 이 링크를 Ctrl하고 클릭하면)

이렇게 Swagger 문서가 뜬다.

이렇게 내용을 수정하면,

이렇게 결과가 나온다.